Referencia de comandos

Los comandos buscan el .taiapiproject desde el directorio actual, y los que leen schemas, también el proyecto de tai-sql: lo cómodo es ejecutarlos desde el directorio que contiene a los dos. Ver El proyecto por dentro.

Si la API está más abajo de lo que alcanza esa búsqueda, -P, --project-dir PATH (o la variable TAI_API_PROJECT_DIR) indica la carpeta de su .taiapiproject. Va antes del comando (tai-api -P chatbot/api generate) y no cambia de directorio: tai-sql sigue buscando su proyecto desde el actual. init no la admite.

Un error que el desarrollador puede arreglar sale con su mensaje, su solución y código de salida 1, sin traza. Los códigos están en Códigos de error.

tai-api init PROJECT

Crea el proyecto: el .taiapiproject, el pyproject.toml, el paquete de la API con su config.py y resources/, el dockerfile y el entrypoint.sh.

Opción
-n, --namespace TEXT	El paquete Python de la API. Por defecto, api
-p, --path PATH	El directorio padre donde se crea. Por defecto, el actual
-a, --app-dir TEXT	Dónde va el paquete dentro del proyecto. Por defecto, . (la raíz)
--install / --no-install	Instalar las dependencias al terminar

El proyecto se crea en <path>/<namespace>: tai-api init mi-api deja ./api/, con el paquete api/api/ dentro. PROJECT es el nombre (name).

tai-api install

Instala las dependencias del proyecto —poetry install con su pyproject.toml— en el entorno virtual activo. Necesita Poetry ≥ 2.2.1.

Opción
-y, --yes	No pedir confirmación
--dev	En vez de eso, instala en el entorno del CLI lo que necesita tai-api dev para ejecutar la API (FastAPI, uvicorn, el driver, tai-keycloak…), según la autenticación

tai-api generate

Regenera la API desde los schemas de tai-sql: el cliente de tai-sql, los endpoints, la autenticación, el arranque, los diagramas y, si hay bloque frontend, el cliente TypeScript. Al terminar avisa —sin tocar nada— si las reglas para asistentes se quedaron atrás o si resources/ es de una revisión anterior.

Con bloque frontend, antes de escribir nada lee el package.json más cercano a su output_dir (sin ejecutar npm): si el bloque activa algo que el frontend no tiene —react, svelte, zod—, falla (A012) y dice qué instalar o qué quitar. Y con la sesión con cookie avisa de lo que el config.py de la API haría perder la sesión: un ROOT_PATH distinto del base_path y ALLOWED_ORIGINS = ["*"] (ver Desplegar el frontend).

Opción
-s, --schema TEXT	Solo ese schema
--all	Todos los schemas del proyecto de tai-sql

Sin opciones, regenera los de generated_schemas; la primera vez, pregunta cuáles. El schema auth no se genera así: es de tai-api auth init. Un schema que ya no existe en tai-sql se retira de la API.

tai-api dev

Arranca la API con recarga (fastapi dev), sin autorización: todo endpoint responde sin token, y cada respuesta lo dice con la cabecera X-Tai-Auth: off. Si faltan dependencias, dice cuáles e indica tai-api install --dev. No arranca si la autenticación generada lee otra variable que secret_key_name (A041): se cambió sin regenerar.

Opción
-w, --auth	Con la autorización activa, como en producción

tai-api auth

Comando	Qué hace
auth init	Elige el modo —Database o Keycloak—, pregunta su configuración, crea rbac/main.py y regenera. Con Database, crea además schemas/auth.py en el proyecto de tai-sql
auth status	La autenticación configurada, y si la generada ya no corresponde a secret_key_name
auth switch	Cambia de un modo al otro y regenera la autenticación, el arranque y los endpoints. La política de sesión (auth.session) se conserva. Después, tai-api rbac push

Ver Autenticación.

tai-api rbac

Comando	Qué hace
rbac show	Lo declarado en rbac/<realm>.py y lo que cambiaría en el backend, sin tocar nada
rbac push	Lo aplica: crea el realm si no existe, sincroniza permisos, roles y reglas de RLS, y prepara la sesión con cookie en Keycloak. Pide confirmación, y avisa antes de borrar algo con usuarios
rbac new-realm	Crea el fichero rbac/<realm>.py de un realm nuevo

show y push aceptan -r, --realm TEXT (solo ese realm) y -v, --verbose (el detalle de cada permiso). Ver Permisos y roles.

tai-api rules

Comando	Qué hace
rules install [--force]	Instala las reglas para asistentes de IA en <raíz del repositorio>/.claude/rules/_platform/tai-api/: las de esta versión y las derivadas del proyecto. Sin --force, no pisa lo editado a mano
rules check	Sale con código distinto de cero si no están al día: para el CI
rules diff	En qué se diferencian las instaladas de las de esta versión

Ver Reglas para asistentes de IA.

tai-api set-mcp

Expone las lecturas de la API como herramientas MCP en /mcp: añade fastapi-mcp al proyecto, marca mcp en el .taiapiproject y regenera. Necesita un schema por defecto en tai-sql (tai-sql set-default-schema <nombre>).