Saltar al contenido
Aula en la nube
Proyecto 2 · CLI tareas con IA · Presencial y semipresencial

Tu propia herramienta de terminal: tareas

Vas a construir una CLI: un programa que se usa escribiendo órdenes en la terminal y que trabaja con tus ficheros — ordena descargas, renombra fotos, limpia temporales, resume documentos — mediante acciones que defines tú en un fichero acciones.json. Combina lo que sabe hacer el sistema operativo con lo que sabe hacer la IA, y se instala con una sola orden en Linux, Windows y macOS.

El hilo del proyecto 2

Cada uno se construye una herramienta útil para sí mismo, y reutilizable.

  1. Detectas una tarea que te hace perder tiempo
  2. La automatizas con tu propia CLI, construida con OpenCode
  3. La reutilizas: una orden, cada vez que la necesites

En esta página

Tareas que te hacen perder tiempo

Tus acciones tienen que resolver un problema tuyo: mira tu carpeta de descargas y piensa qué te gustaría no volver a hacer a mano. Estas son ideas, de menos a más difícil; empieza por arriba. Las de IA llegan en la semana 3.

  1. RenombrarsistemaFotos con su fecha (2026-10-26_001.jpg), quitar espacios y tildes de nombres, numerar entregas.
  2. OrdenarsistemaDescargas por tipo (PDF, imágenes, comprimidos, instaladores) o apuntes por asignatura según el nombre.
  3. Limpiar y detectarsistemaTemporales con más de 30 días, duplicados por hash (mismo contenido, distinto nombre), informe de espacio en disco por carpeta.
  4. Resumir con IAIAResumir PDFs o textos largos, generar el README de una carpeta de proyecto, convertir apuntes desordenados en Markdown limpio.
  5. Renombrar por contenido con IAIALa IA lee el principio de cada documento y propone un nombre que diga lo que es (con --simular primero).
  6. Acciones encadenadassistema + IAOrdenar → quitar duplicados → resumir lo nuevo → informe final. Una orden, varios pasos.

De la tarea pesada a una orden

Tarea pesadaa mano, cada vezLa describesen acciones.jsonUna ordenen tu terminalHecha solasiempre igualy la reutilizas

Desliza el diagrama de lado para verlo entero

Tu herramienta, útil para ti y reutilizable: lo que hoy te hace perder tiempo, mañana es una orden.

Por qué importa

Los desarrolladores viven en la terminal. Git, los gestores de paquetes, los servidores, la integración continua y los propios agentes de IA son CLI. Quien sabe usarlas automatiza; quien sabe construirlas crea herramientas que usan otros.

Y la construyes de otra manera: desde este proyecto trabajas de forma agéntica con OpenCode, un agente de programación open source conectado a los modelos de IA locales del centro. Tú decides qué se hace y apruebas cada cambio; el agente lee tu repo, propone y edita. El chat queda para consultas.

Python 3.12

+ Typer + uv

acciones.json

tus acciones, fuera del código

Sistema + IA

ficheros reales y modelos

3 sistemas

Linux · Windows · macOS

OpenCode

agente del centro · modelos locales

Qué es una CLI

CLI (Command Line Interface, interfaz de línea de órdenes) es un programa que se controla escribiendo texto: tecleas una orden, pulsas Intro, el programa hace su trabajo, escribe un resultado y termina. Sin ventanas, sin botones. Lo contrario es una GUI (Graphical User Interface): ventanas, menús y ratón.

ventanas y ratón

Gana la GUI

  • Explorar algo que no conoces: ves las opciones en pantalla.
  • Tareas visuales: retocar una foto, maquetar, editar vídeo a mano.
  • Usuarios que no quieren aprender órdenes.

texto y teclado

Gana la CLI

  • Automatizar y repetir: la misma orden hoy, mañana y 300 veces.
  • Encadenar herramientas con tuberías (|): la salida de una es la entrada de otra.
  • Servidores sin pantalla: el 90 % de Internet se administra por SSH.
  • Scripts, tareas programadas (cron) e integración continua (CI): nadie hace clic ahí.
  • Dejar rastro: una orden se copia, se documenta y se repite exacta.

Terminal, shell y CLI: no es lo mismo

La ventana

Terminal

La aplicación que muestra texto y recoge lo que tecleas: Terminal de Linux o macOS, Windows Terminal, la terminal integrada de VS Code.

El intérprete

Shell

El programa que lee tu orden y la lanza: bash (Linux), zsh (macOS), PowerShell (Windows). Cada una tiene su sintaxis: por eso hay órdenes que cambian de un sistema a otro.

El programa

CLI

La herramienta que la shell ejecuta: git, curl, uv… y, dentro de dos semanas, tareas. Funciona igual desde cualquier shell.

Una dentro de otra

Terminal · la ventanaShell · el intérprete: bash, zsh o PowerShellgitmáquina del tiempocurlhabla HTTPuvinstala paquetestu CLIdentro de 2 semanas$ git log --oneline -5tú escribes, la shell lanza

Desliza el diagrama de lado para verlo entero

Abres una terminal, dentro corre una shell, y en ella escribes órdenes que lanzan CLI.

Anatomía de una orden

Esta es una orden real de tu futura herramienta. Separada en piezas se entiende todo lo demás:

tareasprogramael comandoinstaladoejecutarsubcomandoqué hacer(un verbo)ordenar-descargasargumento 1qué acción ejecutar(de acciones.json)~/Descargasargumento 2sobre qué carpeta(opcional)--simularopción (flag)cómo: enseña quéharía, sin tocar

Desliza el diagrama de lado para verlo entero

Se lee como una frase: «herramienta, haz esto, con esto, aquí, de esta manera».

Ayuda y argumentos

Y estas son las otras piezas que tiene cualquier CLI seria (y tendrá la tuya):

Ayuda (--help)

Toda CLI decente se explica sola. Es lo primero que pruebas con una herramienta nueva y lo primero que se evalúa en la tuya.

Terminal
tareas --helptareas ejecutar --help

Argumentos vs opciones

Argumento: dato posicional, normalmente obligatorio (QUÉ). Opción: empieza por - o --, tiene nombre y suele ser opcional (CÓMO). Un flag es una opción sí/no.

Terminal
tareas listar ~/Descargas            # argumentotareas listar ~/Descargas --json     # + opción (flag)tareas --config otro.json acciones   # opción con valor

Canales y salida del programa

stdin, stdout y stderr

Tres canales: entrada estándar, salida estándar (resultados) y salida de error (avisos y fallos). Separarlos permite redirigir solo lo útil.

Terminal
tareas listar > lista.txt          # stdout a un ficherotareas validar 2> errores.txt      # stderr a otrotareas listar --json | jq length   # tubería: stdout entra en jq

Códigos de salida

Al acabar, el programa devuelve un número: 0 = todo bien, distinto de 0 = algo falló. Los scripts y la CI deciden con él. En tu CLI: 0 bien · 1 fallo al ejecutar · 2 error de uso · 3 configuración inválida.

Terminal
tareas validarecho $?            # bash/zsh → 0, 1, 2 o 3echo $LASTEXITCODE # PowerShell

Entorno y configuración

Variables de entorno

Valores que el sistema le pasa al programa sin escribirlos en la orden: rutas, idioma, claves de API (nunca en el código).

Terminal
export TAREAS_MODELO=llama3   # bash/zsh$env:TAREAS_MODELO = "llama3"  # PowerShell

Fichero de configuración

Lo que cambia poco y no quieres teclear cada vez. En tu proyecto, las acciones viven en acciones.json, no en el código.

Terminal
tareas acciones                     # usa ./acciones.jsontareas --config ~/mis.json acciones

Formato y preguntas

Formato de salida

Para personas: tablas y colores. Para máquinas: --json (estable, sin colores). Una buena CLI ofrece las dos.

Terminal
tareas listar ~/Descargas          # tabla bonitatareas listar ~/Descargas --json   # para otro programa

Interactiva vs no interactiva

Antes de borrar, pregunta (¿Seguro? [s/N]). Pero en un script nadie responde: --si confirma sin preguntar. Y --simular enseña qué haría sin tocar nada.

Terminal
tareas ejecutar limpiar-temporales --simulartareas ejecutar limpiar-temporales        # preguntatareas ejecutar limpiar-temporales --si   # no pregunta

Las CLI que usa el mundo

Muchas de las herramientas más potentes de la informática no tienen ventanas. Algunas que verás (o usarás) este curso:

Código y versiones

  • gitControl de versiones: la máquina del tiempo de tu código.git log --oneline -5
  • ghGitHub desde la terminal: repos, issues, PR y releases.gh repo create cli-tareas --public
  • OpenCodela que usarásAgente de código open source que vive en la terminal: lee tu repo, ejecuta órdenes (con tu permiso) y propone cambios. Primos: Claude Code, Codex CLI, Gemini CLI.opencode

Red, descargas y multimedia

Red y descargas

  • curlHabla HTTP: descarga ficheros, prueba APIs, instala herramientas.curl -s https://api.github.com/users/octocat
  • yt-dlpDescarga vídeo y audio de cientos de webs (respeta derechos y licencias).yt-dlp -x --audio-format mp3 URL
  • rsyncCopias y copias de seguridad incrementales, en local o por red.rsync -av ~/Proyectos/ /media/usb/copia/

Multimedia y documentos

  • ffmpegLa navaja suiza del vídeo y el audio: convertir, recortar, extraer.ffmpeg -i clase.mov -c:v libx264 clase.mp4
  • magick (ImageMagick)Convierte, redimensiona y retoca imágenes por lotes.magick foto.png -resize 50% foto.jpg
  • pandocConvierte documentos entre formatos: Markdown, Word, PDF, HTML.pandoc apuntes.md -o apuntes.docx

Búsqueda y entornos

Buscar y filtrar

  • rg (ripgrep)Busca texto en miles de ficheros en milisegundos.rg "TODO" src/
  • fzfBuscador difuso interactivo: elige de una lista tecleando.ls | fzf
  • jqLee, filtra y transforma JSON en la terminal.jq ".acciones[].nombre" acciones.json

Sistema y entornos

  • dockerEjecuta aplicaciones en contenedores aislados y reproducibles.docker run --rm -it python:3.12
  • uv · pip · npmGestores de paquetes: instalan librerías y herramientas.uv add typer
  • htop · btopMonitor de procesos, CPU y memoria en la terminal.btop

Ayuda e IA

  • tldrEjemplos prácticos de cualquier orden, sin leer el manual entero.tldr tar
  • ollamaDescarga y ejecuta modelos de IA en tu propio equipo.ollama run llama3.2 "Resume esto"

Encadenar herramientas

lslista los ficherosfzfeliges uno tecleandoTu pantallasolo lo elegidostderravisos y fallos, apartela tubería |su stdout2> errores.txt

Desliza el diagrama de lado para verlo entero

Encadenar herramientas con tuberías (|): la salida de una es la entrada de otra.

Truco para la vida

Antes de buscar en Google cómo se usa una orden, prueba orden --help, tldr orden o man orden. Y si tu herramienta no se explica así de bien, aún no está terminada.

Cómo se desarrolla una CLI de verdad

Las herramientas profesionales no salen de un prompt gigante. Salen de este ciclo, paso a paso, con un commit al acabar cada uno. Es el que seguirás:

1 · Specpara quién y qué2 · Interfazlas órdenes exactas3 · Núcleoel motor, sin Typer4 · Casos feosmensajes claros5 · Pruebaspytest6 · Empaquetadocomando instalable7 · Releasev1.0.0 etiquetaday vuelta a empezar

Desliza el diagrama de lado para verlo entero

Cada acción nueva repasa el ciclo en pequeño, con un commit al acabar cada paso.

El ciclo, paso a paso

  1. Spec de 10 líneasPara quién es, qué problema resuelve, qué órdenes tendrá, qué NO hará. Si no cabe en 10 líneas, aún no sabes qué quieres.docs/spec.md
  2. InterfazLas órdenes y opciones exactas, como las teclearía alguien. Se diseña antes que el código: es el contrato con quien la usa.tareas --help
  3. Núcleo (motor)La lógica que hace el trabajo, separada de la interfaz: el motor no sabe nada de Typer ni de colores. Así se prueba y se reutiliza.motor.py
  4. Errores y casos feosCarpeta que no existe, JSON mal escrito, fichero abierto, sin permisos, sin red, nombre con tildes. Mensajes claros, nunca un traceback.errores.py
  5. Pruebaspytest comprueba que cada acción hace lo que dice en una carpeta temporal. Si cambias algo y se rompe, te enteras antes que tu usuario.tests/
  6. Empaquetado e instalaciónpyproject.toml con su entry point: tu programa se convierte en un comando que se instala con una orden.uv tool install
  7. ReleaseVersión etiquetada (v1.0.0), notas de cambios y README con instalación probada en otro sistema.git tag v1.0.0

El método del curso

Tú escribes la spec y el acciones.json (decides qué hace), el agente (OpenCode) implementa con tu permiso, y tú auditas: lees el código, pruebas casos feos y haces commits pequeños con mensajes que cuentan el proceso. Guarda tus prompts clave en docs/prompts.md.

Lo que no sabes explicar, no lo entregas.

Cómo vas a trabajar: con un agente

Hasta ahora le pedías código a un chat y lo copiabas. Desde este proyecto, el código lo escribe un agente dentro de tu repo, y tú diriges. Se usará todo el curso, en presencial y en semipresencial; este proyecto es la introducción.

Para consultas

Chat

  • Preguntas, responde con texto y tú copias.
  • No ve tu repo ni ejecuta nada: si se equivoca, no se entera.
  • Sigue valiendo para dudas y explicaciones.

Para construir

Agente (OpenCode)

  • Lee tus ficheros, propone un plan, edita y lanza órdenes.
  • Cada cambio te lo pide primero, y comprueba el resultado.
  • Más potencia, más responsabilidad: tú apruebas y tú auditas.

El flujo de cada sesión

Siempre el mismo:

Tú decidesPlan piensaBuild haceIntenciónPide planHazloAuditaCommit/newsiguiente tarea

Desliza el diagrama de lado para verlo entero

Tú decides al principio y al final; plan piensa y build hace en medio. Y vuelta a empezar con la siguiente tarea.

Los seis pasos del flujo

  1. Tú decidesEscribes la intención: la spec, tu acciones.json o el criterio de aceptación de la tarea.
  2. PlanAgente plan (Shift+Tab): «explícame cómo lo harías y qué ficheros tocarías». Lees el plan y lo corriges.
  3. Build aprobando diffsAgente build (Shift+Tab): «hazlo». Lees cada diff y cada orden antes de aceptarla.
  4. AuditasLees el código y pruebas con --simular en ~/pruebas-tareas, con casos feos. ¿Mal? /undo o le explicas el fallo.
  5. Commit tuyogit add + git commit los haces tú, pequeños y con un mensaje que cuente el paso. El prompt clave, a docs/prompts.md.
  6. Sesión nueva/new para cada tarea y /compact si la conversación se alarga: contexto limpio, menos errores.

Qué configuras en tu repo

La conexión con los modelos del centro va en tu configuración global (con variables de entorno: la clave nunca acaba en un fichero que subas a git). En el repo van las reglas del juego para el agente:

  • opencode.jsonSemana 1Permisos: qué puede hacer solo (leer, git status), qué te pregunta (editar, casi todas las órdenes) y qué nunca (git push, rm, leer .env).
  • AGENTS.mdSemana 1Lo genera /init y lo editas tú: stack, órdenes del proyecto y normas (pathlib, utf-8, nada de commits ni push).
  • .opencode/skills/acciones-json/SKILL.mdSemana 2Skill: las reglas de tu acciones.json, que el agente carga cuando toca acciones.
  • .opencode/commands/nueva-accion.mdSemana 2Comando /nueva-accion: añadir una acción siempre con los mismos pasos.
  • .opencode/agents/revisor.mdSemana 2Subagente revisor de solo lectura: se lo pides por su nombre y busca errores y casos feos antes de cada commit.

Usamos la última versión estable de OpenCode 2. Cómo se instala, se conecta y se configura, en la guía.

El gancho: OpenCode es una CLI

La herramienta con la que vas a programar tu CLI es… una CLI. OpenCode tiene ayuda, opciones, subcomandos, fichero de configuración y códigos de salida: todo lo que estás a punto de construir. Úsala con ojo de quien la va a imitar.

Guía: OpenCode con los modelos del centro →

Tecnologías para hacer una CLI

Casi cualquier lenguaje sirve. Cada uno paga un precio distinto:

Python · Typer / Click / argparse

la del curso
A favor
Legible, librerías para todo (ficheros, PDF, IA), multiplataforma, rapidísimo de escribir. argparse viene de serie; Typer genera ayuda y autocompletado desde los tipos.
En contra
Necesita Python instalado (uv lo resuelve); arranque algo más lento; no da un único ejecutable de serie.
Hechas así
aws-cli, yt-dlp, httpie, pip, Ansible

Node.js · commander / oclif

A favor
Ecosistema npm enorme; ideal si ya trabajas en JavaScript; buena integración con herramientas web.
En contra
Necesita Node; node_modules pesados; asincronía que complica scripts sencillos.
Hechas así
npm, Vercel CLI, Heroku CLI, Angular CLI

Go · cobra

A favor
Un único binario sin dependencias, compila para cualquier sistema, arranque instantáneo.
En contra
Más verboso; tipado y compilación que ralentizan el primer prototipo.
Hechas así
kubectl, gh, docker, hugo

Rust y scripts de shell

Rust · clap

A favor
Velocidad máxima y seguridad de memoria; binarios únicos; clap es excelente.
En contra
Curva de aprendizaje dura; compilaciones lentas.
Hechas así
ripgrep, fd, bat, uv

Scripts Bash / PowerShell

A favor
Ya están instalados; perfectos para pegar 5 órdenes existentes.
En contra
Frágiles al crecer, difíciles de probar y no multiplataforma (Bash ≠ PowerShell).
Hechas así
instaladores, nvm, scripts de despliegue

Por qué Python 3 + Typer + uv

Legible

Puedes leer y auditar lo que escribe el agente aunque estés empezando.

Multiplataforma

El mismo código funciona en Linux, Windows y macOS si sigues cuatro reglas.

El agente lo domina

Python es el lenguaje en el que más código ha visto cualquier modelo: menos inventos.

Una orden para instalar

uv instala Python, dependencias y tu herramienta como comando global.

Typer hace el trabajo sucio

A partir de los tipos de tus funciones genera --help, validación de argumentos y autocompletado.

Rich incluido

Tablas, colores y barras de progreso que funcionan también en Windows Terminal.

Un hola mundo con Typer

Fíjate: no escribes nada sobre la ayuda ni sobre cómo leer los argumentos. Typer lo deduce de nombre: str, veces: int = 1 y gritar: bool = False.

hola.py
import typer​app = typer.Typer(help="Tu primera CLI con Typer.")​​@app.command()def hola(nombre: str, veces: int = 1, gritar: bool = False):    """Saluda a NOMBRE tantas VECES como pidas."""    for _ in range(veces):        texto = f"Hola, {nombre}"        print(texto.upper() if gritar else texto)​​if __name__ == "__main__":    app()
Terminal
uv run --with typer hola.py Ana --veces 2 --gritar
HOLA, ANAHOLA, ANA

Lo que Typer deduce de los tipos

nombre: strsin valor por defectoargumento obligatorionombre [required]veces: int = 1con valor por defectoopción con valor--veces [default: 1]gritar: bool = Falseverdadero o falsoflag con su contrario--gritar / --no-gritarTyper lo deduce

Desliza el diagrama de lado para verlo entero

Argumento obligatorio, opciones con valor por defecto, un flag con su contrario y autocompletado para tu shell. Gratis.

La ayuda que genera Typer

Salida de: uv run --with typer hola.py --help
 Usage: hola.py [OPTIONS] {nombre}​ Saluda a NOMBRE tantas VECES como pidas.​╭─ Arguments ──────────────────────────────────────────────────────────╮│ *    nombre      <str>  [required]                                   │╰──────────────────────────────────────────────────────────────────────╯╭─ Options ────────────────────────────────────────────────────────────╮│ --veces                                <int>  [default: 1]           ││ --gritar                --no-gritar           [default: no-gritar]   ││ --install-completion                          Install completion for ││                                               the current shell.     ││ --show-completion                             Show completion for    ││                                               the current shell, to  ││                                               copy it or customize   ││                                               the installation.      ││ --help                                        Show this message and  ││                                               exit.                  │╰──────────────────────────────────────────────────────────────────────╯

Multiplataforma: Linux primero

…pero en todas partes. En el aula trabajas en Linux. Pero tu herramienta la instalará gente con Windows y macOS (y si eres de semipresencial, tu propio equipo puede ser cualquiera de los tres). Python lo pone fácil si respetas seis reglas.

Tu código Pythonpathlib · utf-8 · shutilel mismo en los tresLinuxshell: bashseparador /fin de línea LFWindowsshell: PowerShellseparador \fin de línea CRLFmacOSshell: zshtambién usa /también LF

Desliza el diagrama de lado para verlo entero

Lo que cambia de un sistema a otro lo resuelven pathlib, la codificación explícita y .gitattributes.

Rutas y la ~

Rutas con pathlib, nunca concatenando

Windows usa \ y Linux /. Path elige el separador correcto por ti.

MALruta = carpeta + "/" + nombre
BIENruta = Path(carpeta) / nombre

La ~ hay que expandirla

~ lo entiende la shell, no Python. Sin expanduser() busca una carpeta llamada «~».

MALopen("~/Descargas/lista.txt")
BIENPath("~/Descargas").expanduser() / "lista.txt"

Codificación y órdenes del sistema

Codificación explícita

En Windows la codificación por defecto puede no ser UTF-8: las tildes y la ñ se rompen.

MALPath("acciones.json").read_text()
BIENPath("acciones.json").read_text(encoding="utf-8")

Nada de shell=True ni os.system

mv no existe en PowerShell clásico, un nombre con espacios lo rompe y abre la puerta a inyecciones.

MALos.system("mv " + origen + " " + destino)
BIENshutil.move(origen, destino)

Saltos de línea y colores

Saltos de línea normalizados

Windows usa CRLF y Linux LF. Sin esto, git marca cambios fantasma en todas las líneas.

MAL(sin .gitattributes)
BIEN# .gitattributes * text=auto

Colores con Rich

Los códigos ANSI a mano salen como basura en algunas consolas. Rich detecta lo que soporta cada una.

MALprint("\033[31mError\033[0m")
BIENconsole.print("[red]Error[/red]")

Y en la semana 4, GitHub Actions ejecutará tus pruebas en Ubuntu, Windows y macOS a la vez en cada git push: si algo solo funciona en tu equipo, te enterarás.

Equivalencias bash ↔ PowerShell

PowerShell tiene alias con los nombres de Linux (ls, cp, mv…), pero las opciones no siempre coinciden. Entre paréntesis, el nombre «de verdad» del cmdlet.

Quiero…bash / zsh (Linux, macOS)PowerShell (Windows)
Listar ficherosls -laGet-ChildItem (o ls)
Cambiar de carpetacd ~/Proyectoscd ~\Proyectos
¿Dónde estoy?pwdpwd (Get-Location)
Crear carpetamkdir -p pruebas/amkdir pruebas\a (New-Item -ItemType Directory)
Copiarcp origen destinocp origen destino (Copy-Item)
Mover / renombrarmv viejo nuevomv viejo nuevo (Move-Item)
Borrarrm fichero · rm -r carpetarm fichero · rm -r carpeta (Remove-Item)
Ver un ficherocat acciones.jsoncat acciones.json (Get-Content)
¿Dónde está un comando?which tareasGet-Command tareas · where.exe tareas
Leer una variableecho $HOMEecho $env:USERPROFILE
Código de salidaecho $?echo $LASTEXITCODE

Instalarla para que sea útil

Un script que solo funciona con python src/tareas/cli.py desde su carpeta es un ejercicio. Una herramienta se teclea por su nombre desde cualquier carpeta. ¿Cómo lo consigue git?

El PATH

Cuando escribes tareas, la shell busca un ejecutable con ese nombre en una lista de carpetas: la variable de entorno PATH. Un comando está «instalado» cuando hay un ejecutable suyo en alguna de ellas.

Terminal
echo $PATH        # bash/zsh$env:Path          # PowerShellwhich tareas       # ¿cuál se ejecuta? (Get-Command en Windows)

El entry point

En pyproject.toml declaras qué función se ejecuta al teclear el comando. Al instalar, uv crea el ejecutable tareas en una carpeta del PATH (~/.local/bin en Linux y macOS).

pyproject.toml
[project.scripts]tareas = "tareas.cli:app"   # comando = "módulo:objeto"

Del nombre a tu código

Tecleasel nombreLa shellbusca en el PATHLo encuentraen ~/.local/binEntry point«tareas.cli:app»Tu programaapp de cli.pyEn Windows: %USERPROFILE%\.local\bin\tareas.exe

Desliza el diagrama de lado para verlo entero

Instalar y desinstalar

Mientras desarrollas

Modo editable: cada cambio que guardas se nota al momento, sin reinstalar.

Terminal
cd cli-tareasuv tool install --editable .tareas --help

Para otra persona

Directamente desde tu repo público de GitHub. Con uv o, si no lo tiene, con pipx.

Terminal
uv tool install git+https://github.com/TU-USUARIO/cli-tareas# o bienpipx install git+https://github.com/TU-USUARIO/cli-tareas

Desinstalar

Una buena herramienta se va igual de limpia que llegó. Su configuración de usuario (si la hay) se borra aparte.

Terminal
uv tool uninstall tareasuv tool list        # comprobar que ya no está

Dónde vive cada cosa

QuéLinux / macOSWindows
El comando instalado~/.local/bin/tareas%USERPROFILE%\.local\bin\tareas.exe
acciones.json (por defecto)./acciones.json, en la carpeta donde lanzas la orden, o la que indiques con --config
Config de usuario (avance)~/.config/tareas/%APPDATA%\tareas\

La ruta de config de usuario no se escribe a mano: la librería platformdirs devuelve la correcta en cada sistema.

Cómo comprobar que funciona en otro sistema

  1. Pide a un compañero (mejor con otro sistema operativo) que siga solo tu README, sin ayuda tuya.
  2. Instala con la orden de uv tool install git+… y prueba tareas --help y tareas version desde otra carpeta.
  3. Crea una carpeta de pruebas con ficheros de ejemplo y lanza cada acción con --simular y luego de verdad.
  4. Prueba un nombre con tildes y espacios (Apuntes de Física.pdf) y una ruta con ~.
  5. Rompe a propósito el acciones.json: tareas validar debe decir qué falla y salir con código 3.
  6. Desinstala y comprueba que tareas ya no existe. Todo lo que haya fallado, al README o a un issue.

El proyecto: qué tiene que hacer tu CLI

El comando de ejemplo se llama tareas y el repo cli-tareas (público en GitHub). Puedes elegir otro nombre, pero estas son las órdenes de referencia:

tareas --help
Ayuda general con todas las órdenes (la genera Typer).
tareas version
Muestra la versión instalada (0.1.0 al empezar).
tareas listar [CARPETA]
Tabla con nombre, tipo, tamaño y fecha de cada fichero. Por defecto, la carpeta actual.
tareas acciones
Lista las acciones definidas en acciones.json con su descripción.
tareas validar
Comprueba acciones.json y dice exactamente qué campo falla (código 3 si es inválido).
tareas ejecutar NOMBRE [CARPETA] --simular
Muestra qué haría la acción sin tocar nada.
tareas ejecutar NOMBRE [CARPETA] --si
La ejecuta sin preguntar (para scripts).
tareas --config RUTA …
Opción global: otro fichero de acciones (por defecto ./acciones.json).

Códigos de salida: 0 bien · 1 fallo al ejecutar · 2 error de uso (lo pone Typer) · 3 configuración inválida.

acciones.json: el corazón del proyecto

Las acciones no se escriben en el código: se describen en este fichero y el motor las interpreta. Este es el esquema de referencia; tú lo adaptas a tus acciones y lo documentas en tu README.

acciones.json
{  "version": 1,  "acciones": [    { "nombre": "ordenar-descargas", "descripcion": "Mueve los PDF y documentos de Descargas a Documentos/PDF",      "tipo": "mover", "origen": "~/Descargas", "filtro": { "extensiones": [".pdf", ".docx"] }, "destino": "~/Documentos/PDF" },    { "nombre": "renombrar-fotos", "descripcion": "Renombra fotos con su fecha: 2026-10-26_001.jpg",      "tipo": "renombrar", "filtro": { "extensiones": [".jpg", ".jpeg", ".png"] }, "plantilla": "{fecha:%Y-%m-%d}_{n:03}{ext}" },    { "nombre": "limpiar-temporales", "descripcion": "Borra .tmp con más de 30 días",      "tipo": "borrar", "filtro": { "patron": ".*\\.tmp$", "mas_antiguo_que_dias": 30 }, "confirmar": true }  ]}

Campo a campo

version
Versión del esquema del fichero. Si algún día cambias el formato, sabrás leer los antiguos.
acciones
Lista de acciones. Añadir una nueva no exige tocar el código: ese es el objetivo.
nombre
Identificador que se teclea: tareas ejecutar ordenar-descargas. Minúsculas y guiones, único.
descripcion
Lo que verá quien ejecute tareas acciones. Una frase que diga qué hace.
tipo
Qué clase de acción es: mover, renombrar, copiar, borrar… (y en la semana 3, las de IA). Cada tipo es una clase en acciones.py.
origen / destino
Carpetas sobre las que trabaja. Admiten ~ (se expande con expanduser). Si no hay origen, se usa la CARPETA de la orden.
filtro
Qué ficheros le afectan: extensiones, patron (expresión regular sobre el nombre), mas_antiguo_que_dias…
plantilla
Para renombrar: {fecha:%Y-%m-%d} es la fecha del fichero, {n:03} un contador a 3 cifras y {ext} la extensión original.
confirmar
true en acciones destructivas: pregunta antes de actuar salvo que pases --si.

Qué hace ordenar-descargas

acciones.json · esta acción
    { "nombre": "ordenar-descargas", "descripcion": "Mueve los PDF y documentos de Descargas a Documentos/PDF",      "tipo": "mover", "origen": "~/Descargas", "filtro": { "extensiones": [".pdf", ".docx"] }, "destino": "~/Documentos/PDF" },

Descargas, antes

~/
Descargas/
apuntes-tema1.pdf
contrato.docx
foto-playa.jpg
Documentos/PDF/
tareas ejecutar ordenar-descargas

Descargas, después

~/
Descargas/
foto-playa.jpgno es PDF ni docx: se queda
Documentos/PDF/
apuntes-tema1.pdf
contrato.docx

Qué hace renombrar-fotos

acciones.json · esta acción
    { "nombre": "renombrar-fotos", "descripcion": "Renombra fotos con su fecha: 2026-10-26_001.jpg",      "tipo": "renombrar", "filtro": { "extensiones": [".jpg", ".jpeg", ".png"] }, "plantilla": "{fecha:%Y-%m-%d}_{n:03}{ext}" },

Fotos, antes

~/Imágenes/viaje/
IMG_2041.jpg
IMG_2042.jpg
Captura de pantalla.png
notas.txt
tareas ejecutar renombrar-fotos ~/Imágenes/viaje

Fotos, después

~/Imágenes/viaje/
2026-10-26_001.jpg
2026-10-26_002.jpg
2026-10-26_003.png
notas.txtno es una foto: se queda

Qué hace limpiar-temporales

acciones.json · esta acción
    { "nombre": "limpiar-temporales", "descripcion": "Borra .tmp con más de 30 días",      "tipo": "borrar", "filtro": { "patron": ".*\\.tmp$", "mas_antiguo_que_dias": 30 }, "confirmar": true }

Temporales, antes

~/pruebas-tareas/
cache-viejo.tmphace 45 días
sesion.tmphace 2 días
informe.pdf
tareas ejecutar limpiar-temporales ~/pruebas-tareasAntes de borrar pregunta: ¿Seguro? [s/N]

Temporales, después

~/pruebas-tareas/
sesion.tmpmenos de 30 días: se queda
informe.pdfno es .tmp: se queda

Estructura del repositorio

Cada fichero tiene un único trabajo.

cli-tareas/
pyproject.toml[project.scripts] tareas = "tareas.cli:app"
README.md
.gitignore.venv/, __pycache__/, .env, *.egg-info, dist/
.gitattributes* text=auto
acciones.jsonTUS acciones (lo escribes tú)
docs/adr/0001-configuracion-externa.md
src/tareas/
__init__.py__version__ = "0.1.0"
__main__.pypermite: python -m tareas
cli.pyinterfaz Typer: órdenes, opciones, salida
config.pyleer y VALIDAR acciones.json
motor.pyclase Motor: ejecuta una Accion sobre una carpeta
acciones.pyclases Accion (mover, renombrar, copiar, borrar…)
errores.pyTareasError, ConfigError, AccionNoValida
tests/semana 4

Por dónde pasa una orden

Tu ordenen la terminalacciones.jsonlo escribes túcli.pyhabla contigoconfig.pyvalida el JSONmotor.pyhace el trabajoacciones.pymover, borrar…Tus ficherosde pruebaerrores.pynunca un traceback

Desliza el diagrama de lado para verlo entero

cli.py habla con la persona, motor.py y acciones.py hacen el trabajo, config.py desconfía del JSON.

La capa de IA y el modo sin red

Semana 3

La capa de IA

Acciones de tipo IA (resumir, generar README, renombrar por contenido) que llaman a un modelo — los mismos del centro con los que trabaja OpenCode, o el que configures. La clave va en un .env ignorado por git desde el primer commit, con un .env.example documentado.

Semana 3

Modo sin red

Si no hay red o falta la clave, tu CLI no revienta con un traceback: lo explica en una línea y sigue ofreciendo todas las acciones que no necesitan IA.

Paso a paso, en la Sesión 3 · La capa IA.

Seguridad desde el día 1

.gitignore con .env antes del primer commit; nunca claves en el repo ni en el chat; acciones destructivas siempre con --simular primero y confirmación.

Y prueba siempre en ~/pruebas-tareas, nunca en tus ficheros reales hasta que funcione.

Planificación: las cuatro semanas

  1. Semana 1

    26-30 oct

    Sesión 1 · Arranque →
    • Moverte por carpetas, crear, copiar y borrar en tu terminal (bash o PowerShell).
    • Instalar uv y Python 3.12; crear el proyecto con uv init --package y añadir Typer.
    • Escribir tu spec de 10 líneas y el .gitignore (con .env) ANTES del primer commit.
    • Primeras órdenes: --help, version y listar con tabla Rich.
    • Instalarla con uv tool install --editable . y lanzarla desde cualquier carpeta.
    • Diseñar tu acciones.json con al menos 3 acciones propias (no las del ejemplo).
    • config.py que valida el JSON y dice qué campo falla; errores.py con tus excepciones.
    • Clases Accion y Motor separadas de la interfaz; órdenes acciones, validar y ejecutar.
    • --simular siempre primero y confirmación antes de borrar; todo en ~/pruebas-tareas.
    • ADR 0001: por qué configuración externa y no acciones escritas en el código.
  2. Semana 3

    9-13 nov

    Sesión 3 · Capa IA →
    • 2 acciones con IA tuyas, la clave fuera del repo y un modo sin red.
    • context7 por MCP, solo cuando hace falta.
  3. Semana 4

    16-20 nov

    Sesión 4 · Release →
    • pytest y Actions en 3 sistemas, opencode run en un script y la release v1.0.

Qué haces la semana 1

Objetivo · semana 1

Perderle el miedo a la terminal y tener un comando tareas que existe de verdad.

Ir a la sesión →

OpenCode · semana 1

  • Instalar OpenCode (la última versión estable) y conectarlo a los modelos del centro.
  • uv init y .gitignore a mano y primer commit ANTES de abrir OpenCode (/undo necesita git).
  • opencode.json de permisos en la raíz del repo.
  • /init → AGENTS.md, que revisas y editas tú.
  • plan → build para crear cli.py (version + listar), aprobando cada diff; /undo cuando algo sale mal.

Producto · semana 1

Repo cli-tareas en GitHub con tareas --help, tareas version y tareas listar funcionando, opencode.json y AGENTS.md, y varios commits tuyos que cuentan el proceso.

Qué haces la semana 2

Objetivo · semana 2

Que tu herramienta haga cosas útiles definidas en un fichero que escribes tú.

Ir a la sesión →

OpenCode · semana 2

  • Tu acciones.json lo escribes tú, sin IA.
  • Skill del proyecto acciones-json con las reglas del esquema (compruébala con /skills).
  • Comando personalizado /nueva-accion para añadir acciones siempre igual.
  • Subagente revisor de solo lectura y /review antes de cada commit.

Producto · semana 2

3 acciones propias funcionando con --simular, tareas validar con mensajes claros, ADR escrito, skill + comando + revisor en .opencode/ y commits pequeños.

Qué haces la semana 3

Objetivo · semana 3

Que tu herramienta lea: resuma, ponga nombre y clasifique con los modelos del centro, sin filtrar la clave y sin dejar a nadie tirado sin red.

Ir a la sesión →

OpenCode · semana 3

  • MCP: context7 en opencode.json, apagado, y encendido con /mcps solo para consultar la documentación de httpx.
  • Lo que trae el MCP también se audita: la forma obsoleta de httpx 0.28.
  • Skill acciones-json al día con los tipos de IA.

Producto · semana 3

2 acciones con IA tuyas, comprobar-ia, modo sin red, ninguna clave en el historial, la skill y el README al día y el ADR-0002.

Qué haces la semana 4

Objetivo · semana 4

Demostrar que funciona, que sigue funcionando y que otra persona la instala con una orden.

Ir a la sesión →

OpenCode · semana 4

  • El agente escribe las pruebas; tú auditas cada assert.
  • opencode run sin pantalla: el revisor en un script (scripts/revisar.sh).
  • Un borrador de CHANGELOG desde git log… que hay que corregir.

Producto · semana 4

28 pruebas o más en verde en tres sistemas, la etiqueta v1.0.0 con su release y su CHANGELOG, y la instalación de un compañero.

El calendario de los dos grupos

Semana 1 · 26-30 octSemana 2 · 2-6 novSemana 3 · 9-13 novSemana 4 · 16-20 novPresencialSemipresencialSesión 1arranqueSesión 2acciones y motorSesión 3capa IA y MCPSesión 4pruebas y v1.0Quincena 326 oct → 6 novQuincena 49 → 20 novcomprobación 6 noventrega 20 nov

Desliza el diagrama de lado para verlo entero

Cómo se organiza cada grupo

Presencial

  • Es tu segundo proyecto: línea individual de 4 h/semana en el aula, en paralelo a la startup en grupo (las otras 4 h).
  • Equipos del aula con Linux: la terminal es bash desde el primer minuto.
  • Herramientas: terminal y OpenCode conectado a los modelos de IA locales del centro. El chat, solo para consultas.
  • Cada sesión acaba con commit y push: lo que no está en GitHub no existe.

Semipresencial

  • Quincena 3 = estas dos semanas; comprobación de proceso el 6 nov: 3 acciones propias funcionando + ADR + commits reales.
  • Quincena 4 (9 → 20 nov): IA, pruebas, release y entrega el 20 nov.
  • OpenCode también en casa (por ejemplo, en la terminal de VS Code), conectado a los modelos del centro. El chat de Copilot de Microsoft 365, solo para consultas.
  • Terminal y conexión desde casa: en la tutoría colectiva de arranque, de presencia obligatoria (fecha en el aula virtual). Tu equipo puede ser Windows, Linux o macOS.

Cómo se evalúa

Primero, la puerta de entrada: si falla cualquiera de estos mínimos, el proyecto no se evalúa (aunque el resto esté genial).

  • Se instala siguiendo el README y la orden de ayuda (--help) funciona.
  • Al menos 3 acciones propias definidas en el fichero de configuración (acciones.json) funcionan.
  • Ninguna clave ni secreto en el repositorio ni en su historial.
  • Historial git real: mínimo 10 commits con mensajes que cuentan el proceso.

Cuánto pesa cada criterio

Acciones predefinidas funcionando · 20 %Configuración externa (acciones.json) · 15 %Capa IA, secretos y modo sin red · 15 %Robustez: excepciones y entradas feas · 15 %Diseño en clases y módulos · 10 %Pruebas y calidad · 15 %Instalación, documentación y proceso · 10 %

Desliza el diagrama de lado para verlo entero

Los siete criterios suman 100: pesan más las acciones (20); el resto, entre 10 y 15.

Rúbrica: acciones y configuración

Cada criterio, casilla a casilla. Apunta a la última: Excelente.

Acciones predefinidas funcionando

peso 20

Lo que tu herramienta hace de verdad con tus ficheros.

Insuficiente · 0 %
Ninguna acción funciona de principio a fin, o solo el ejemplo de partida.
En desarrollo · 50 %
1-2 acciones propias que funcionan en el caso fácil; salida confusa o efectos inesperados.
Competente · 80 %
3-4 acciones propias útiles, con salida clara (qué se ha hecho y sobre qué ficheros) y modo simulación.
Excelente · 100 %
5 o más acciones propias útiles, combinables, con salida clara y sin efectos sorpresa (simulación previa o confirmación antes de borrar o sobrescribir).

Configuración externa (acciones.json)

peso 15

Las acciones viven en un fichero que escribes tú, no dentro del código.

Insuficiente · 0 %
Las acciones están escritas a mano dentro del código.
En desarrollo · 50 %
Existe acciones.json pero el código lo lee sin comprobar nada: un error en el JSON rompe el programa.
Competente · 80 %
Esquema propio documentado en el README; el JSON se valida antes de ejecutar y los errores dicen qué campo falla.
Excelente · 100 %
Además: añadir una acción no exige tocar el código y hay un ADR que justifica por qué configuración externa y no código.

Rúbrica: IA y robustez

Capa IA, secretos y modo sin red

peso 15

IA donde aporta, sin filtrar claves y sin depender de ella para todo.

Insuficiente · 0 %
Sin IA, o con la clave escrita en el código o subida al repositorio.
En desarrollo · 50 %
Una acción con IA que funciona, pero si no hay red o falta la clave la CLI se rompe con un traceback.
Competente · 80 %
Al menos 2 acciones con IA útiles; clave en .env (ignorado por git desde el primer commit) y .env.example documentado.
Excelente · 100 %
Al menos 2 acciones con IA útiles; ninguna clave en el historial; si no hay red, la CLI lo explica y sigue con las acciones sin IA.

Robustez: excepciones y entradas feas

peso 15

Qué pasa cuando el usuario se equivoca o el disco no es como esperabas.

Insuficiente · 0 %
Cualquier error (ruta inexistente, JSON roto) termina en un traceback.
En desarrollo · 50 %
Se capturan algunos errores, con mensajes genéricos («error»).
Competente · 80 %
Errores previsibles controlados con mensajes humanos y código de salida distinto de 0; nunca se pierde un fichero por un fallo a medias.
Excelente · 100 %
Excepciones propias (ConfigError, AccionNoValida…) con mensajes humanos; ningún traceback ante errores previsibles; aserciones en desarrollo.

Rúbrica: diseño y pruebas

Diseño en clases y módulos

peso 10

Cómo está organizado el código por dentro.

Insuficiente · 0 %
Todo en un único fichero sin funciones ni clases.
En desarrollo · 50 %
Funciones separadas, pero interfaz, lógica y ficheros mezclados.
Competente · 80 %
Módulos separados (cli, motor, acciones, configuración) y clases con una responsabilidad clara.
Excelente · 100 %
Responsabilidades separadas (interfaz, motor, acciones, proveedor IA), visibilidad cuidada y métodos estáticos con sentido (p. ej., fábricas desde la configuración).

Pruebas y calidad

peso 15

Cómo demuestras que funciona y que sigue funcionando.

Insuficiente · 0 %
Sin pruebas automáticas.
En desarrollo · 50 %
Alguna prueba del camino feliz que el alumno no sabe explicar.
Competente · 80 %
Pruebas con pytest del camino feliz y de al menos 1 caso feo, en carpetas temporales (nunca sobre tus ficheros reales).
Excelente · 100 %
Pruebas que cubren el camino feliz y 3 casos feos, ejecutadas en GitHub Actions y auditadas por el alumno (sabe explicar cada aserción).

Rúbrica: instalación y proceso

Instalación, documentación y proceso

peso 10

Que otra persona la instale y la use sin preguntarte nada.

Insuficiente · 0 %
Sin README o sin instrucciones para instalarla.
En desarrollo · 50 %
README con pasos manuales (clonar, crear entorno, ejecutar el .py).
Competente · 80 %
Se instala con una orden (uv tool install / pipx install desde GitHub) y queda disponible como comando en cualquier carpeta; README con ejemplos.
Excelente · 100 %
Se instala con una orden siguiendo el README; release v1.0 etiquetada con changelog; historial con ramas y PR legibles.

La tienes también en el campus del aula. Léela antes de empezar, no después de entregar.

Enlaces