Instalación de Specify CLI

Instalación persistente con uv tool install

La forma recomendada de instalar la CLI de Spec Kit es mediante uv tool install, que descarga el paquete specify-cli directamente desde el repositorio de GitHub y lo configura como un comando global del sistema. A diferencia de una instalación con pip dentro de un entorno virtual, uv tool install crea un entorno aislado exclusivo para la herramienta y la expone en el PATH, de manera que el comando specify queda accesible desde cualquier directorio.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Este comando realiza tres operaciones:

• Clona el repositorio de Spec Kit desde GitHub.
• Crea un entorno virtual aislado con las dependencias necesarias.
• Registra el ejecutable specify en el PATH del sistema.

Una vez completada la instalación, el comando specify está disponible de forma permanente. No es necesario activar ningún entorno virtual ni ejecutar ningún script previo para utilizarlo.

La instalación persistente con uv tool install es la opción recomendada para equipos y proyectos continuos, ya que el comando queda disponible sin configuración adicional en cada sesión de terminal.

Verificar la instalación

Para confirmar que la instalación se ha completado correctamente, se utiliza el comando specify check:

specify check

Este comando diagnostica el estado de la instalación y muestra información sobre las herramientas detectadas en el sistema. Si la salida no muestra errores, la CLI está lista para su uso.

También se puede comprobar que uv reconoce la herramienta instalada:

uv tool list

El resultado debe incluir specify-cli en la lista de herramientas instaladas.

Ejecución puntual con uvx

Si no se desea instalar la CLI de forma permanente, uv ofrece la posibilidad de ejecutar herramientas Python de forma puntual mediante uvx. Este modo descarga la herramienta, la ejecuta y limpia el entorno temporal cuando finaliza.

uvx --from git+https://github.com/github/spec-kit.git specify init mi-proyecto

La ventaja de uvx es que siempre ejecuta la última versión disponible del repositorio, sin necesidad de gestionar actualizaciones manualmente. Es útil para pruebas rápidas o para usuarios que prefieren no mantener herramientas instaladas de forma global.

La desventaja es que cada ejecución descarga las dependencias de nuevo, lo que añade latencia al inicio del comando. Para uso habitual, la instalación persistente es más práctica.

| Método | Comando | Persistencia | Velocidad | |---|---|---|---| | Instalación persistente | uv tool install | Permanente en PATH | Rápida tras instalación | | Ejecución puntual | uvx | Temporal | Más lenta (descarga cada vez) |

Soporte cross-platform: Bash y PowerShell

Spec Kit genera scripts auxiliares que complementan la funcionalidad de los slash commands. Estos scripts automatizan tareas como la gestión de ramas Git, la creación de directorios para features y la preparación de archivos de contexto para el agente IA.

La CLI detecta automáticamente el sistema operativo durante la inicialización del proyecto y genera los scripts en el formato adecuado:

• Bash (.sh): para macOS y Linux.
• PowerShell (.ps1): para Windows.

Si se necesita forzar un formato concreto, la opción --script de specify init permite elegir explícitamente:

specify init mi-proyecto --script sh

specify init mi-proyecto --script ps

En la mayoría de los casos, dejar que la CLI seleccione el formato automáticamente es la opción más adecuada. La opción manual es útil en entornos donde el shell por defecto no coincide con el que se va a utilizar (por ejemplo, cuando se usa WSL en Windows y se necesitan scripts Bash en lugar de PowerShell).

Los scripts generados por Spec Kit son auxiliares al flujo de trabajo. Los slash commands principales funcionan independientemente del tipo de script, ya que se ejecutan a través del agente IA.

Consideraciones para Windows

En Windows, los scripts de PowerShell pueden requerir ajustar la política de ejecución para permitir la ejecución de scripts no firmados. Si al ejecutar un script se muestra un error de política de ejecución, se puede habilitar temporalmente con:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Este ajuste solo afecta a la sesión de PowerShell actual y no modifica la configuración global del sistema.

Gestión de la instalación

Actualizar la CLI

Cuando se publica una nueva versión de Spec Kit, se puede actualizar la CLI sin desinstalarla previamente. El flag --force indica a uv que reemplace la versión instalada:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

Después de la actualización, specify check confirma que la nueva versión se ha instalado correctamente.

Actualizar la CLI es independiente de actualizar los archivos del proyecto. La CLI es la herramienta global, mientras que los archivos del proyecto (templates, scripts, slash commands) se actualizan por separado con specify init --here --force.

Desinstalar la CLI

Si en algún momento se necesita eliminar la CLI del sistema:

uv tool uninstall specify-cli

Este comando elimina el entorno aislado y retira el comando specify del PATH. Los proyectos inicializados con Spec Kit no se ven afectados, ya que los archivos generados (templates, scripts, slash commands) son independientes de la CLI.

Resolución de problemas comunes

Si el comando specify no se encuentra después de la instalación, las causas más habituales son:

• PATH no actualizado: cerrar y reabrir la terminal suele resolver el problema, ya que la sesión recarga las variables de entorno.
• uv no está en el PATH: verificar que uv está correctamente instalado ejecutando uv --version.
• Conflicto de nombres: en algunos sistemas puede existir otro ejecutable con el nombre specify. Ejecutar which specify (en Bash) o Get-Command specify (en PowerShell) muestra la ruta del ejecutable que se está utilizando.

flowchart TB
    I["uv tool install specify-cli"] --> V["specify check"]
    V -->|OK| R["CLI lista"]
    V -->|Error| D{"Diagnóstico"}
    D -->|PATH| T["Reiniciar terminal"]
    D -->|uv no encontrado| U["Reinstalar uv"]
    D -->|Conflicto| W["Verificar which specify"]

Este flujo resume los pasos de instalación y las acciones de diagnóstico habituales cuando la CLI no responde tras la instalación.