Referencia de la CLI
Referencia completa de todos los comandos de la CLI de FastAPI-fastkit.
Opciones globales
Todos los comandos admiten estas opciones globales:
Opciones globales
| Opción | Descripción |
|---|---|
--version |
Muestra la versión de FastAPI-fastkit |
--help |
Muestra el mensaje de ayuda |
Ejemplos
$ fastkit --version
FastAPI-fastkit version 1.0.0
$ fastkit --help
Usage: fastkit [OPTIONS] COMMAND [ARGS]...
FastAPI-fastkit CLI
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
addroute Add a new route to FastAPI project
init Create a new FastAPI project
list-templates List available FastAPI templates
runserver Start FastAPI development server
startdemo Create FastAPI project from template
Comandos
init
Crea un nuevo proyecto FastAPI con configuración interactiva.
Sintaxis
Opciones
| Opción | Descripción | Por defecto |
|---|---|---|
--interactive |
Configuración guiada: preset de arquitectura y después selección de funcionalidades | off |
--config <path> |
Crea el proyecto a partir de un archivo de configuración guardado, sin prompts | - |
--save-config <path> |
Con --interactive, escribe la configuración respondida en esta ruta |
- |
--project-name |
Nombre del proyecto (se pide si se omite) | - |
--author |
Nombre del autor (se pide si se omite) | - |
--author-email |
Email del autor (se pide si se omite) | - |
--description |
Descripción del proyecto (se pide si se omite) | - |
--package-manager |
Gestor de paquetes a usar (pip, uv, pdm, poetry) | uv |
--dry-run |
Muestra los archivos y paquetes que se crearían, sin escribir nada | off |
--no-venv |
Omite la creación del entorno virtual (implica --no-install) |
off |
--no-install |
Omite la instalación de dependencias | off |
--yes / -y |
No pide confirmación antes de sobrescribir archivos existentes al desplegar el proyecto in situ | off |
--help |
Muestra la ayuda del comando | - |
Archivos de configuración (--config / --save-config)
Las respuestas de una sesión interactiva son un simple mapeo, y ese mapeo puede viajar en un archivo. Así la creación de un proyecto se convierte en algo que puedes hacer commit, revisar y reproducir.
# grabar una sesión interactiva
$ fastkit init --interactive --save-config fastkit.config.json
# reproducirla más tarde, sin ningún prompt
$ fastkit init --config fastkit.config.json
Si no pasas --save-config, una ejecución interactiva que llega al final
pregunta si quieres guardar las selecciones y dónde. Ese prompt solo aparece
cuando hay una persona delante del terminal — las ejecuciones con pipe o en
CI no preguntan nada y activan el guardado con el flag.
Los formatos soportados se eligen según la extensión del archivo:
| Extensión | Disponibilidad |
|---|---|
.json |
Siempre (biblioteca estándar) |
.toml |
Siempre (biblioteca estándar) |
.yaml / .yml |
Solo cuando PyYAML está instalado — fastkit no lo añade como dependencia de ejecución |
Un archivo cargado debe contener un mapeo en su nivel superior con al menos
project_name, author y author_email. Después se valida con las mismas
reglas que usan los prompts interactivos (forma del nombre del proyecto,
formato del email, all_dependencies debe ser una lista), y se informa de
todos los problemas antes de escribir nada. Un archivo que solo enumera
selecciones de funcionalidades — sin all_dependencies — se expande a través
del builder interactivo, de modo que una configuración escrita a mano y una
sesión del asistente resuelven el mismo conjunto de paquetes.
Un ejemplo mínimo:
{
"project_name": "orders-api",
"author": "Developer Kim",
"author_email": "developer@example.com",
"description": "Domain-oriented orders service",
"architecture_preset": "domain-starter",
"package_manager": "uv"
}
Esquema del archivo de configuración
Todo archivo de configuración — escrito a mano o producido por
--save-config — pasa por el mismo normalizador antes de llegar al generador
(normalize_project_config en
backend/project_builder/config_schema.py). Una clave desconocida, una
opción desconocida para un eje conocido o un valor de tipo incorrecto se
rechaza indicando el nombre problemático y la lista de valores realmente
permitidos, en lugar de ignorarse en silencio.
| Clave | Forma | Notas |
|---|---|---|
project_name, author, author_email |
string | Obligatorias |
description |
string | Obligatoria |
architecture_preset (alias preset) |
"minimal" | "single-module" | "classic-layered" | "domain-starter" |
Si aparecen ambas formas, deben coincidir |
package_manager |
"pip" | "uv" | "pdm" | "poetry" |
|
database |
string, o {"type": <choice>} |
PostgreSQL, MySQL, MongoDB, Redis, SQLite, None |
authentication, async_tasks, testing, caching, monitoring, migrations, logging |
string, o {"type": <choice>} |
Ejes de selección única — consulta el catálogo de funcionalidades más arriba para ver las opciones de cada eje |
utilities, tooling |
lista de strings | Ejes de selección múltiple — mismo catálogo para las opciones |
deployment |
lista de strings | Subconjunto de Docker, docker-compose; elegir docker-compose añade Docker automáticamente |
custom_packages |
lista de strings | Paquetes adicionales que se instalan tal cual |
Cada eje acepta su opción sin más ("authentication": "JWT") o la forma de
mapeo {"type": ...} que usan database y los propios metadatos
[tool.fastapi-fastkit] de un proyecto ("authentication": {"type": "JWT"})
— ambas se normalizan a la misma forma canónica, y --save-config siempre
escribe de vuelta la forma canónica de string simple.
Una configuración que usa la mayoría de los ejes:
{
"project_name": "orders-api",
"author": "Developer Kim",
"author_email": "developer@example.com",
"description": "Domain-oriented orders service",
"architecture_preset": "domain-starter",
"package_manager": "uv",
"database": "PostgreSQL",
"authentication": "JWT",
"async_tasks": "Celery",
"caching": "Redis",
"migrations": "Alembic",
"tooling": ["ruff", "makefile"],
"deployment": ["Docker"]
}
La misma configuración en TOML:
project_name = "orders-api"
author = "Developer Kim"
author_email = "developer@example.com"
description = "Domain-oriented orders service"
architecture_preset = "domain-starter"
package_manager = "uv"
database = "PostgreSQL"
authentication = "JWT"
async_tasks = "Celery"
caching = "Redis"
migrations = "Alembic"
tooling = ["ruff", "makefile"]
deployment = ["Docker"]
Previsualizar y omitir pasos
--dry-run muestra el árbol que se crearía y los paquetes que se instalarían
— con el gestor de paquetes que los instalaría — y después termina sin tocar
el disco:
--no-install se detiene después de crear el entorno virtual;
--no-venv omite también el entorno (y, por tanto, la instalación).
Ambos son útiles en contenedores, en CI y en cualquier lugar donde el
entorno se gestione fuera de fastkit.
Despliegue in situ y confirmación de sobrescritura (--yes / -y)
Cuando un proyecto se despliega in situ — en el workspace actual en lugar de
en una carpeta de proyecto nueva — fastkit pregunta "Overwrite these files?"
antes de sustituir cualquier archivo que ya exista. --yes (o su forma corta
-y) omite esa confirmación y procede con la sobrescritura. No afecta al
prompt independiente "Do you want to proceed with project creation?", que se
sigue mostrando. En un entorno no interactivo (stdin no es un TTY, como en CI
o en una ejecución con pipe), la confirmación de sobrescritura se omite
automáticamente incluso sin --yes.
Prompts interactivos
El comando init te pedirá:
- Nombre del proyecto: nombre del directorio y del paquete
- Nombre del autor: información del autor del paquete
- Email del autor: email de contacto del paquete
- Descripción del proyecto: descripción breve del proyecto
- Selección del stack: elige entre minimal, standard o full
- Selección del gestor de paquetes: elige entre pip, uv, pdm o poetry (a menos que lo especifiques con
--package-manager)
Opciones de stack
Stack MINIMAL:
fastapi- Framework FastAPIuvicorn- Servidor ASGIpydantic- Validación de datospydantic-settings- Gestión de configuración
Stack STANDARD:
- Todos los paquetes del stack MINIMAL
sqlalchemy- Toolkit SQL y ORMalembic- Herramienta de migraciones de base de datospytest- Framework de pruebas
Stack FULL:
- Todos los paquetes del stack STANDARD
redis- Almacén de datos en memoriacelery- Cola distribuida de tareas
Catálogo de funcionalidades del builder interactivo (--interactive)
fastkit init --interactive recorre un catálogo distinto, basado en ejes, en
lugar del stack minimal/standard/full anterior (fuente de verdad:
FastkitConfig.PACKAGE_CATALOG en core/settings.py, y
DynamicConfigGenerator.build_artifacts() para lo que genera cada opción).
Cada eje tiene None (omitir) como valor por defecto; utilities y
tooling son de selección múltiple.
Ahora cada selección genera código real, no solo paquetes instalados —
consulta la matriz de presets de arquitectura / funcionalidades
para ver en qué se diferencian minimal / single-module (main.py
regenerado) y classic-layered / domain-starter (main.py conservado,
avisos de cableado manual).
| Eje | Opciones | Paquetes instalados | Archivos generados |
|---|---|---|---|
database |
PostgreSQL, MySQL, MongoDB, Redis, SQLite, None | PostgreSQL: asyncpg, sqlalchemy · MySQL: aiomysql, sqlalchemy · MongoDB: motor · Redis: redis[hiredis] · SQLite: sqlalchemy, aiosqlite |
Un módulo de configuración de base de datos en la ruta del preset (p. ej. src/config/database.py) |
authentication |
JWT, OAuth2, FastAPI-Users, Session-based, None | JWT: pyjwt[crypto], pwdlib[argon2] · OAuth2: authlib, itsdangerous, httpx · FastAPI-Users: fastapi-users[sqlalchemy], pyjwt[crypto], pwdlib[argon2] · Session-based: itsdangerous |
Un módulo de configuración de auth en la ruta del preset; OAuth2 y Session-based añaden además la configuración de middleware en main.py |
async_tasks |
Celery, Dramatiq, None | Celery: celery[redis], redis[hiredis] · Dramatiq: dramatiq[redis], redis[hiredis] |
<pkg>/worker.py (worker en segundo plano) + <pkg>/features/tasks.py (rutas de tareas) |
testing |
Basic, Coverage, Advanced, None | Basic: pytest, pytest-asyncio, httpx · Coverage: + pytest-cov · Advanced: + faker, factory-boy |
pytest.ini; Advanced añade además tests/factories.py y tests/test_factories.py |
caching |
Redis, None | Redis: redis[hiredis], fastapi-cache2, jinja2 |
<pkg>/features/cache.py (endpoints con caché) |
monitoring |
Loguru, OpenTelemetry, Prometheus, None | Loguru: loguru · OpenTelemetry: opentelemetry-api, opentelemetry-sdk, opentelemetry-instrumentation-fastapi, opentelemetry-exporter-otlp-proto-http · Prometheus: prometheus-client, prometheus-fastapi-instrumentator |
Sin archivo independiente — se cablea directamente en main.py (import / lifespan / setup) |
utilities (selección múltiple) |
CORS, Rate-Limiting, Pagination, WebSocket, None | CORS: ninguno (integrado en FastAPI) · Rate-Limiting: slowapi · Pagination: fastapi-pagination · WebSocket: websockets |
CORS y Rate-Limiting se cablean directamente en main.py; Pagination añade <pkg>/features/pagination.py y WebSocket añade <pkg>/features/websocket.py |
migrations |
Alembic, None | Alembic: alembic |
alembic.ini, alembic/env.py, alembic/script.py.mako, una revisión base alembic/versions/<id>_initial.py, scripts/migrate.sh — solo cuando el eje de base de datos es una base de datos SQL |
tooling (selección múltiple) |
ruff, pre-commit, github-actions, devcontainer, makefile, None | ruff: ruff · pre-commit: pre-commit · github-actions / devcontainer / makefile: ninguno |
ruff fusiona un bloque [tool.ruff] en pyproject.toml (o escribe ruff.toml en proyectos pip); pre-commit escribe .pre-commit-config.yaml; github-actions escribe .github/workflows/test.yml; devcontainer escribe .devcontainer/devcontainer.json; makefile escribe Makefile |
logging |
structured, None | Ninguno (solo logging + json de la stdlib) |
<pkg>/logging_config.py (logging JSON estructurado + middleware de request-id), cableado en main.py |
Sea cual sea la selección, cada proyecto generado obtiene los endpoints
/health y /ready en main.py, y --dry-run muestra exactamente este
conjunto de archivos antes de escribir nada.
Ejemplos
$ fastkit init
Enter the project name: my-api
Enter the author name: John Doe
Enter the author email: john@example.com
Enter the project description: My awesome API
Select stack (minimal, standard, full): standard
Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y
✨ FastAPI project 'my-api' has been created successfully!
Estructura generada
Crea un proyecto con esta estructura:
my-api/
├── .venv/ # Entorno virtual
├── src/
│ ├── __init__.py
│ ├── main.py # Aplicación FastAPI
│ ├── core/
│ │ ├── __init__.py
│ │ └── config.py # Configuración
│ ├── api/
│ │ ├── __init__.py
│ │ ├── api.py # Conjunto de routers de la API
│ │ └── routes/
│ │ ├── __init__.py
│ │ └── items.py # Ruta de ejemplo
│ ├── crud/
│ │ ├── __init__.py
│ │ └── items.py # Operaciones CRUD
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── items.py # Esquemas Pydantic
│ └── mocks/
│ ├── __init__.py
│ └── mock_items.json # Datos de prueba
├── tests/
├── scripts/
├── requirements.txt
├── setup.py
└── README.md
addroute
Añade una nueva ruta de API a un proyecto FastAPI existente.
Sintaxis
Argumentos
| Argumento | Descripción | Obligatorio |
|---|---|---|
ROUTE_NAME |
Nombre de la nueva ruta (se recomienda en plural) | Sí |
PROJECT_DIR |
Directorio del proyecto bajo tu espacio de trabajo (por defecto ., el directorio actual) |
No |
Opciones
| Opción | Descripción | Por defecto |
|---|---|---|
--layout [classic-layer\|domain] |
Estructura del módulo de ruta generado; anula los metadatos del preset | Automático según el preset |
--help |
Muestra la ayuda del comando | - |
Ejemplos
$ cd my-api
$ fastkit addroute users
Adding New Route
┌──────────────────┬──────────────────────────────────────────┐
│ Project │ my-api │
│ Route Name │ users │
│ Target Directory │ ~/my-api │
└──────────────────┴──────────────────────────────────────────┘
Do you want to add route 'users' to project 'my-api'? [Y/n]: y
✨ Successfully added new route 'users' to project 'my-api'
También puedes apuntar a un proyecto bajo tu espacio de trabajo por nombre sin tener que hacer cd:
Archivos generados
Con --layout=classic-layer, crea estos archivos bajo el paquete de la aplicación:
src/api/routes/users.py- Handlers de rutasrc/crud/users.py- Operaciones CRUDsrc/schemas/users.py- Esquemas Pydantic
Con --layout=domain, crea domains/users/ con __init__.py,
models.py, schemas.py, repository.py, service.py y router.py.
La entidad tiene id: int y name: str, con un repositorio en memoria funcional.
Ambos layouts actualizan el router de API existente y lo conectan a la aplicación
si hace falta. Las rutas siguen el paquete real de la aplicación, incluido src/app/.
Sin la opción, [tool.fastapi-fastkit].preset = "domain-starter" selecciona
domain. Cuando falta preset, el preset se infiere a partir de template;
fastapi-domain-starter también selecciona domain. Los demás presets y los proyectos sin
ninguno de esos metadatos seleccionan classic-layer. Un preset desconocido recurre a classic-layer con una
advertencia. La selección explícita no cambia el preset del proyecto.
El comando muestra el layout seleccionado antes de la confirmación. Volver a ejecutarlo conserva los archivos existentes, restaura los que faltan y evita registros duplicados del router. Los módulos con el mismo nombre de layouts distintos pueden coexistir mediante alias de import. El generador no comprueba conflictos de método/ruta HTTP. La migración es manual.
Endpoints generados
El layout de dominio crea estos endpoints (mostrados con /api/v1 como prefijo
existente de la aplicación):
| Método | Endpoint | Descripción |
|---|---|---|
GET |
/api/v1/users |
Listar entidades, 200 |
POST |
/api/v1/users |
Crear una entidad, 201 |
GET |
/api/v1/users/{entity_id} |
Leer una entidad, 200 o 404 |
PUT |
/api/v1/users/{entity_id} |
Reemplazar una entidad, 200 o 404 |
DELETE |
/api/v1/users/{entity_id} |
Eliminar una entidad, 204 vacío o 404 |
POST y PUT aceptan un name de 1 a 120 caracteres. Los IDs los asigna el
repositorio, y PUT los conserva. No se genera ningún endpoint PATCH para los dominios.
El almacenamiento es local al proceso, se pierde al reiniciar y es independiente entre dominios;
reemplaza el repositorio para tener persistencia duradera. Las pruebas pueden inyectar un
repositorio nuevo a través del servicio y sobrescribir get_users_service.
El layout clásico conserva sus stubs GET/POST/PUT/PATCH/DELETE existentes en
/<route_name>/ para que los implementes.
Dónde se inserta el código
addroute necesita dos cosas del proyecto: dónde poner los nuevos imports y
dónde registrar el router. Las plantillas y los entrypoints generados marcan
ambos lugares con comentarios ancla:
# src/app/api/router.py
from src.app.api import health
# fastkit:imports
api_router = APIRouter()
api_router.include_router(health.router)
# fastkit:routes
Mantén esos comentarios en su sitio cuando edites el archivo — addroute
inserta justo debajo de # fastkit:imports y # fastkit:routes. Un
proyecto que los haya perdido (o que se generó antes de que existieran las
anclas) sigue funcionando: fastkit recurre a una inserción basada en AST que
encuentra por sí misma el bloque de imports y los registros de routers. Las
anclas simplemente hacen que el resultado sea predecible.
addroute también lee el bloque [tool.fastapi-fastkit] del proyecto para
localizar el entrypoint, así que funciona en estructuras que el escaneo del
disco por sí solo clasificaría mal.
startdemo
Crea un proyecto FastAPI a partir de una plantilla ya preparada.
Sintaxis
Opciones
| Opción | Descripción | Por defecto |
|---|---|---|
--project-name |
Nombre del proyecto (se pide si se omite) | - |
--author |
Nombre del autor (se pide si se omite) | - |
--author-email |
Email del autor (se pide si se omite) | - |
--description |
Descripción del proyecto (se pide si se omite) | - |
--package-manager |
Gestor de paquetes a usar (pip, uv, pdm, poetry) | uv |
--dry-run |
Muestra los archivos y paquetes que se crearían, sin escribir nada | off |
--no-venv |
Omite la creación del entorno virtual (implica --no-install) |
off |
--no-install |
Omite la instalación de dependencias | off |
--yes / -y |
No pide confirmación antes de sobrescribir archivos existentes al desplegar el proyecto in situ | off |
--help |
Muestra la ayuda del comando | - |
Igual que init, startdemo se niega a ejecutarse cuando el directorio del
proyecto de destino ya existe (Error: Project '{name}' already exists.).
--dry-run es la excepción: como nunca escribe en disco, sí puede apuntar a
un nombre que ya tiene directorio. Consulta
Despliegue in situ y confirmación de sobrescritura
más arriba para ver qué hace --yes al desplegar en el workspace actual.
Prompts interactivos
El comando startdemo te pedirá:
- Nombre del proyecto: nombre del directorio del nuevo proyecto
- Nombre del autor: información del autor del paquete
- Email del autor: email de contacto
- Descripción del proyecto: descripción breve
- Selección del gestor de paquetes: elige entre pip, uv, pdm o poetry (a menos que lo especifiques con
--package-manager)
Plantillas disponibles
| Plantilla | Descripción | Funcionalidades |
|---|---|---|
fastapi-default |
Proyecto FastAPI simple | CRUD básico, datos mock |
fastapi-domain-starter |
Starter orientado a dominios | Una carpeta por concepto de negocio, /health |
fastapi-auth-jwt |
Autenticación JWT | Rotación de access/refresh, argon2id, roles y scopes, Alembic |
fastapi-sqlmodel |
Persistencia asíncrona con SQLModel | SQLModel + SQLAlchemy asíncrono, Alembic, CRUD genérico, paginación |
fastapi-llm-agent |
Agente Claude con streaming | Streaming SSE, bucle de llamadas a herramientas, memoria de conversación |
fastapi-custom-response |
Sistema de respuesta personalizada | Respuestas a medida, paginación |
fastapi-psql-orm |
API FastAPI con PostgreSQL | PostgreSQL, SQLAlchemy, Alembic |
fastapi-mcp |
Servidor Model Context Protocol | Integración con MCP |
fastapi-single-module |
Sandbox de un solo archivo | Un módulo, sin fronteras de paquete |
fastapi-empty |
Proyecto FastAPI mínimo | Configuración mínima |
fastapi-async-crud |
(obsoleta) API de gestión de items async | Sustituida por fastapi-sqlmodel |
fastapi-dockerized |
(obsoleta) API FastAPI dockerizada | Las herramientas de Docker vienen ahora con las plantillas más nuevas |
Las plantillas obsoletas siguen generando proyectos que funcionan; simplemente ya no son puntos de partida recomendados. Consulta ¿Qué starter elegir?.
Ejemplos
$ fastkit startdemo fastapi-psql-orm
Enter the project name: my-blog
Enter the author name: Jane Smith
Enter the author email: jane@example.com
Enter the project description: Blog API with PostgreSQL
Select package manager (pip, uv, pdm, poetry) [uv]: poetry
Do you want to proceed with project creation? [y/N]: y
✨ FastAPI project 'my-blog' from 'fastapi-psql-orm' has been created!
runserver
Arranca el servidor de desarrollo de FastAPI.
Sintaxis
Opciones
| Opción | Corto | Descripción | Por defecto |
|---|---|---|---|
--host |
-h |
Host al que enlazar | 127.0.0.1 |
--port |
-p |
Puerto al que enlazar | 8000 |
--reload |
-r |
Activar recarga automática | True |
--workers |
-w |
Número de workers | 1 |
--help |
Muestra la ayuda del comando | - |
Ejemplos
# Uso básico (configuración por defecto)
$ fastkit runserver
INFO: Uvicorn running on http://127.0.0.1:8000
# Host y puerto personalizados
$ fastkit runserver --host 0.0.0.0 --port 8080
INFO: Uvicorn running on http://0.0.0.0:8080
# Desactivar recarga automática
$ fastkit runserver --no-reload
INFO: Uvicorn running on http://127.0.0.1:8000
# Varios workers (producción)
$ fastkit runserver --workers 4
INFO: Uvicorn running on http://127.0.0.1:8000
Requisitos
- Debe ejecutarse desde el directorio de un proyecto FastAPI
- El proyecto debe exponer una app FastAPI — se resuelve desde
[tool.fastapi-fastkit].app_modulecuando existe y, si no, se descubre buscandomain.py - El entorno virtual debe estar activado
Si ni el entrypoint registrado ni el escaneo encuentran un módulo,
runserver informa de que no ha podido encontrar main.py y se detiene.
list-templates
Lista todas las plantillas de proyecto FastAPI disponibles.
Sintaxis
Opciones
| Opción | Descripción | Por defecto |
|---|---|---|
--help |
Muestra la ayuda del comando | - |
Ejemplos
$ fastkit list-templates
Available Templates
┌─────────────────────────┬───────────────────────────────────┐
│ fastapi-custom-response │ Async Item Management API with │
│ │ Custom Response System │
│ fastapi-dockerized │ Dockerized FastAPI Item │
│ │ Management API │
│ fastapi-empty │ No description │
│ fastapi-async-crud │ Async Item Management API Server │
│ fastapi-psql-orm │ Dockerized FastAPI Item │
│ │ Management API with PostgreSQL │
│ fastapi-default │ Simple FastAPI Project │
└─────────────────────────┴───────────────────────────────────┘
Metadatos del proyecto ([tool.fastapi-fastkit])
Cada proyecto que genera fastkit registra cómo se produjo, en su propio
pyproject.toml:
[tool.fastapi-fastkit]
managed = true
version = "1.4.0"
template = "fastapi-domain-starter"
preset = "domain-starter"
package_manager = "uv"
app_module = "src.app.main:app"
features = ["database:PostgreSQL", "authentication:JWT"]
| Clave | Significado |
|---|---|
managed |
Siempre true; marca el proyecto como gestionado por fastkit |
version |
La versión de fastkit que generó el proyecto |
template |
La plantilla de startdemo, o la plantilla base del preset |
preset |
El preset de arquitectura de init --interactive (se omite en otro caso) |
package_manager |
El gestor usado para construir el entorno |
app_module |
El entrypoint module:attr de uvicorn |
features |
Lista plana "<category>:<choice>" de las selecciones interactivas |
Este bloque es la única fuente de verdad del entrypoint del proyecto:
fastkit runserver lee app_module de aquí antes de recurrir al escaneo del
árbol, fastkit addroute lo usa para localizar la aplicación y los
Dockerfiles generados usan el mismo valor en su CMD.
El bloque se escribe al final de la generación — los gestores de paquetes
reescriben pyproject.toml mientras resuelven dependencias, así que hay que
estamparlo después — y una regeneración posterior lo sustituye en lugar de
añadir una segunda copia. Editar app_module a mano es la forma soportada de
indicar a fastkit una estructura que has reorganizado tú mismo.
Variables de entorno
FastAPI-fastkit respeta estas variables de entorno:
| Variable | Descripción | Por defecto |
|---|---|---|
FASTKIT_CONFIG_DIR |
Directorio de configuración | ~/.fastkit |
FASTKIT_TEMPLATES_DIR |
Directorio de plantillas personalizadas | Plantillas integradas |
FASTKIT_LOG_LEVEL |
Nivel de log | INFO |
FASTKIT_SUBPROCESS_TIMEOUT |
Sustituye todos los timeouts de los subprocesos del gestor de paquetes, en segundos | por operación (30 / 120 / 900) |
Cada llamada al gestor de paquetes tiene su propio límite, para que un
proceso hijo colgado nunca pueda bloquear la CLI: 30 segundos para una
comprobación de disponibilidad, 120 para crear un entorno virtual y 900 para
instalar dependencias. FASTKIT_SUBPROCESS_TIMEOUT sustituye los tres por un
único valor — útil en una red lenta o para fallar rápido en CI. Un valor que
no sea un entero positivo se ignora.
Ejemplos
Archivos de configuración
FastAPI-fastkit puede usar archivos de configuración para los valores por defecto.
Ubicación del archivo de configuración
$FASTKIT_CONFIG_DIR/config.yaml(siFASTKIT_CONFIG_DIRestá definido)~/.fastkit/config.yaml(por defecto)./fastkit.yaml(específico del proyecto)
Formato del archivo de configuración
# ~/.fastkit/config.yaml
default:
author:
name: "Your Name"
email: "your.email@example.com"
project:
stack: "standard"
create_venv: true
install_deps: true
server:
host: "127.0.0.1"
port: 8000
reload: true
templates:
custom_dir: "~/my-templates"
logging:
level: "INFO"
file: "~/.fastkit/logs/fastkit.log"
Flujos de trabajo habituales
1. Crear un proyecto nuevo
2. Añadir funcionalidades a un proyecto existente
3. Usar plantillas para proyectos complejos
# Listar las plantillas disponibles
$ fastkit list-templates
# Crear desde plantilla
$ fastkit startdemo
# Selecciona fastapi-psql-orm para un proyecto con base de datos
# Configurar la base de datos (para la plantilla PostgreSQL)
$ cd my-project
$ docker-compose up -d postgres
$ source .venv/bin/activate
$ alembic upgrade head
$ fastkit runserver
Solución de problemas
Comando no encontrado
Si el comando fastkit no aparece:
-
Comprueba la instalación:
-
Reinstala si hace falta:
-
Comprueba el PATH:
Problemas con el entorno virtual
Si la creación del entorno virtual falla:
-
Comprueba la versión de Python:
-
Comprueba el módulo venv:
-
Entorno virtual manual:
El servidor no arranca
Si fastkit runserver falla:
- Comprueba que estás en el directorio del proyecto
- Verifica que existe
src/main.py -
Activa el entorno virtual:
-
Comprueba errores de sintaxis:
Puerto ya en uso
Si el puerto 8000 está ocupado:
Uso avanzado
Plantillas personalizadas
Puedes crear plantillas personalizadas siguiendo estos pasos:
-
Crear el directorio de la plantilla:
-
Definir la variable de entorno:
-
Usar la plantilla personalizada:
FastAPI-fastkit desde scripts
Puedes usar FastAPI-fastkit en scripts:
#!/bin/bash
# create-microservices.sh
for service in users products orders; do
echo "Creating $service service..."
fastkit init <<EOF
$service-service
Company Team
team@company.com
$service microservice
minimal
y
EOF
cd "$service-service"
fastkit addroute "$service"
cd ..
done
Integración con CI/CD
Ejemplo de flujo de trabajo con GitHub Actions:
name: Test FastAPI-fastkit Project
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: '3.12'
- name: Install FastAPI-fastkit
run: pip install fastapi-fastkit
- name: Create test project
run: |
fastkit init <<EOF
test-project
CI
ci@example.com
Test project
standard
y
EOF
- name: Test project
run: |
cd test-project
source .venv/bin/activate
python -m pytest
Soporte de gestores de paquetes
FastAPI-fastkit soporta varios gestores de paquetes Python para que elijas el que mejor encaje con tu flujo de trabajo.
Gestores soportados
| Gestor | Descripción | Archivo de dependencias | Ideal para |
|---|---|---|---|
| UV (por defecto) | Gestor de paquetes Python rápido | pyproject.toml |
Velocidad y rendimiento |
| PDM | Gestión moderna de dependencias Python | pyproject.toml |
Resolución avanzada de dependencias |
| Poetry | Gestión de dependencias y empaquetado Python | pyproject.toml |
Flujos basados en Poetry |
| PIP | Gestor estándar de paquetes Python | requirements.txt |
Desarrollo tradicional en Python |
Especificar el gestor de paquetes
Configuración global
Puedes definir tu gestor preferido para todos los proyectos:
# Con opciones de línea de comandos
$ fastkit init --package-manager poetry
$ fastkit startdemo --package-manager pdm
Selección por proyecto
Cada proyecto puede usar un gestor distinto. La elección se hace en el momento de la creación y afecta a:
- Formato del archivo de dependencias: cada gestor crea los archivos apropiados
- Gestión del entorno virtual: distintos métodos de activación
- Instalación de dependencias: comandos específicos por gestor
Características de los gestores
UV (por defecto)
- Rápido: basado en Rust, resolución de dependencias extremadamente rápida
- Compatible: sustituye directamente a pip y pip-tools
- Moderno: soporta los metadatos de proyecto PEP 621
PDM
- Moderno: soporta PEP 582 y PEP 621
- Avanzado: resolución de dependencias sofisticada
- Flexible: varias estructuras de proyecto
Poetry
- Consolidado: maduro y muy adoptado
- Integrado: soporte de build y publicación
- Lockfile: poetry.lock para builds reproducibles
PIP
- Estándar: viene con Python
- Compatible: funciona en todas partes
- Simple: gestión de dependencias directa
Trabajar con los proyectos
Tras crear un proyecto con un gestor concreto:
Proyectos UV
cd my-project
uv sync # Instalar dependencias
uv add requests # Añadir nueva dependencia
uv run pytest # Ejecutar comandos dentro del entorno
Proyectos PDM
cd my-project
pdm install # Instalar dependencias
pdm add requests # Añadir nueva dependencia
pdm run pytest # Ejecutar comandos dentro del entorno
Proyectos Poetry
cd my-project
poetry install # Instalar dependencias
poetry add requests # Añadir nueva dependencia
poetry run pytest # Ejecutar comandos dentro del entorno
Proyectos PIP
cd my-project
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
pip install -r requirements.txt
pip install requests
pytest
Próximos pasos
Ahora que conoces la CLI:
- Inicio rápido: Prueba los comandos en la práctica
- Tu primer proyecto: Construye una aplicación completa
- Contribuir: Contribuye a FastAPI-fastkit
Consejos de la CLI
- Usa
--helpcon cualquier comando para ver la ayuda detallada - Configura los valores por defecto para acelerar la creación de proyectos
- Usa plantillas para setups de proyecto complejos
- Combina comandos para crear flujos de trabajo potentes