Referencia del CLI `wsp`

wsp es la herramienta de línea de comandos de AWaC. No la corrés vos directamente — la corre tu agente IA por vos. Sin embargo, todos los flags y formatos de output están documentados acá para que cualquier persona (o agente) pueda entender qué hace cada cosa y diagnosticar problemas.

Última actualización mayor: 2026-05-04 (v1.1.0).

Roadmap del CLI

Versión	Comandos shipped	Fecha
v0.1.0	`init`, `bootstrap`, `templates`, `shortcuts`, `doctor`, `schema`, `--agent-manifest`	2026-05-02
v0.2.0	+ `sync`, `status`	2026-05-03
v0.3.0	+ `scaffold-stack <org>`	2026-05-03
v0.4.0	+ `governance check`	2026-05-03
v0.5.0	+ `scaffold-repo <full> --category <X>`	2026-05-03
v0.6.0	+ schemas `deploy/1` + `devvault/1`, doctor `devvault_config` step	2026-05-03
v0.7.0	+ `deploy <product>`, `secrets check <product>`	2026-05-03
v0.8.0	+ `audit <product>`, scaffold-stack auto-register en core, scaffold-repo `--aws-account`/`--domain` para Cat A descriptions	2026-05-03
v0.9.0	+ scaffold-stack `--update --push-direct` (skip PR, push to main)	2026-05-03
v1.0.0	First public release (MIT license, public reference stacks, OSS launch)	2026-05-03
v1.1.0	+ schemas `awac/2` + `deploy/2` + `lock/2`, bootstrap materializes `.stack/<product>/`, doctor `stack_metadata_drift`, deploy/secrets `--no-overrides`, `init --interactive`/`--yes`, `wsp guide <topic>`, `wsp migrate-deploy <product>`, `wsp templates --json` exposes `requires_confirmation`/`composes_stacks`/`clones_repos`	2026-05-04
v1.2+ (futuro)	`+ promote`, `worktree add/list/remove`, `explain`, `diff`	Planeado

Repo: https://github.com/getGanemo/workspace-cli-oss. Releases (wheels): https://github.com/getGanemo/workspace-cli-oss/releases.

Instalación

Modo user (recomendado)

TAG=v1.1.0
gh release download "$TAG" --repo getGanemo/workspace-cli-oss --pattern '*.whl' --dir /tmp/wsp
pipx install /tmp/wsp/wsp-*.whl

Para automatización, el workflow universal install_wsp (en <transversal-org>/agent-stack-core/workflows/) cubre detección + instalación + gh auth + wsp doctor en 7 pasos.

Modo dev (para hackear el CLI)

git clone https://github.com/getGanemo/workspace-cli-oss ~/dev/workspace-cli
pipx install -e ~/dev/workspace-cli

Requisitos: Python ≥ 3.10, git, pipx, gh autenticado.

Filosofía: CLI agent-first

wsp está diseñado para ser consumido por un agente IA, no por humanos. Esto implica:

Help exhaustivo, no resumido. Cada flag, cada exit code, cada error documentado.
Modo --json en TODO comando. El agente parsea, no scrapea texto.
Errores accionables con code + category + cause + remediation. El agente sabe qué hacer cuando algo falla.
Cero prompts interactivos por default. Si falta info, falla con un error estructurado listando qué falta.
Idempotencia garantizada en bootstrap y sync. Correrlos N veces da el mismo resultado.
Output predecible sin colores ANSI cuando se detecta --json o stdout no es TTY.

Comandos

`wsp init <name> [options]`

Crea un workspace nuevo desde una plantilla. Escribe workspace.yml pero no clona nada (eso es trabajo de bootstrap).

ARGUMENTS:
  <name>                Nombre del workspace.

OPTIONS:
  --template <id>       ID del template del registry. Default: blank.
  --target <path>       Dónde crear la carpeta. Default: <cwd>/<name>.
  --json                Output JSON.

`wsp bootstrap [options]`

Resuelve los stacks declarados, los clona/actualiza, clona repos de producto, compone .agents/ + CLAUDE.md/AGENTS.md. Idempotente.

OPTIONS:
  --update-locks        Forzar resolución completa y reescribir el lock.
  --json                Output JSON.

`wsp sync [options]`

Refresca stacks (cache pulls) y recompone .agents/ + CLAUDE.md/AGENTS.md sin re-clonar product repos.

OPTIONS:
  --json                Output JSON.

`wsp status [options]`

Read-only diff entre workspace.lock.yml y el estado actual: stacks (commit lockfile vs upstream), repos (modified, ahead/behind), agents_drift.

OPTIONS:
  --json                Output JSON.

`wsp scaffold-stack <org> [options]`

Introspecciona un GitHub org y autogenera su agent-stack siguiendo agent-stack-core/awac.yml#org_scaffold. Clasifica cada repo en categorías A–E, detecta módulos Odoo Cat E, y genera awac.yml + templates/feature.yml + README.md. Desde v0.8.0 también auto-registra el shortcut <product> y el template <product>-feature en el core registry.

ARGUMENTS:
  <org>                 GitHub org name.

OPTIONS:
  --update              Repo existe — refrescar awac.yml repos block (ver --push-direct).
  --no-push             Generar el seed localmente; imprimir el path. No tocar GH.
  --no-register         Saltar el auto-register en core. (v0.8.0+)
  --push-direct         (v0.9.0+) Con --update: push directo a main en vez de abrir PR.
                        Para cuando sos owner del repo y el cambio es additive
                        (e.g. durante onboard_new_product Step 4).
  --branch <name>       Override side-branch en --update (sin efecto con --push-direct).
  --json                Output JSON.

BEHAVIOR (default — repo doesn't exist):
  1. gh repo create <org>/agent-stack --private (con descripción governance-compliant).
  2. Clasifica cada repo del org en Cat A/B/C/D + detecta Cat E.
  3. Genera awac.yml + templates/feature.yml + README.md.
  4. Push directo a main.
  5. (v0.8.0+) Auto-register en agent-stack-core/awac.yml (shortcut + template).

BEHAVIOR (--update sin --push-direct, default):
  1. Clona el repo existente.
  2. Reemplaza el bloque `repos:` del awac.yml.
  3. Push a side-branch + abre PR.
  4. (v0.8.0+) Auto-register en core.

BEHAVIOR (--update --push-direct):
  1. Clona el repo existente.
  2. Reemplaza el bloque `repos:` del awac.yml.
  3. Push directo a main (sin PR).
  4. (v0.8.0+) Auto-register en core.

EXAMPLES:
  wsp scaffold-stack <new-product-org>                # primer scaffold
  wsp scaffold-stack <existing-org> --update          # refresh via PR (third-party / sensitive)
  wsp scaffold-stack <my-org> --update --push-direct  # refresh sin PR (own product onboard)
  wsp scaffold-stack <product-org> --no-push          # preview local, no GH calls

`wsp scaffold-repo <full> --category <A|B|C|D|E> [options]`

Crea un repo de producto siguiendo la convención de README + descripción codificada en governance, o audita un README existente y abre PR con las secciones requeridas que falten.

ARGUMENTS:
  <full>                <org>/<name>.

OPTIONS:
  --category {A,B,C,D,E}    Required.
  --update              Repo existe — auditar README y abrir PR si falla.
  --no-push             Generar seed localmente.
  --branch <name>       Override side-branch (--update).
  --aws-account <ID>    (v0.8.0+) AWS account ID para Cat A `infrastructure`.
  --domain <DOMAIN>     (v0.8.0+) Cloudflare domain para Cat A `infrastructure`.
  --json                Output JSON.

CATEGORÍAS REQUIRED SECTIONS:
  A: Purpose · Structure · Usage · Cross-references
  B: Purpose · Public URL · Stack · Local development · Cross-references
  C: Purpose · Stack · Architecture role · Primary consumers · Local development · Tests · Deployment · Cross-references
  D: Purpose · Stack · Usage · Cross-references
  E: Producer product · Manifest · Cross-references

`wsp governance check [options]`

Verifica que awac.yml#org_scaffold no diverja del documento canónico. Reemplaza al CI workflow previo (ADR 008). wsp doctor corre el mismo chequeo.

EXIT CODES:
  0   aligned
  1   divergence detected

`wsp audit <product> [options]`

(v0.8.0+) Read-only audit de un producto contra governance + AWaC convention.

ARGUMENTS:
  <product>             Slug del producto.

OPTIONS:
  --json                Output JSON.

CHECKS (~11):
  cat_a/<repo>_exists           # los 3 Cat A repos en GitHub
  cat_a/<repo>_description      # matcheas governance pattern
  agent_stack/awac_yml_repos    # awac.yml lista repos
  agent_stack/feature_template  # templates/feature.yml presente
  agent_stack/devvault_yml      # válido contra schema devvault/1
  agent_stack/deploy_yml        # válido contra schema deploy/1 o deploy/2 (warn si falta)
  registry/shortcut             # shortcut <product> en core
  registry/template             # template <product>-feature en core

EXIT CODES:
  0   PASS
  1   FAIL (al menos un check falla)

Step 8 obligatorio del workflow onboard_new_product (incluido en el stack core de tu equipo).

`wsp deploy <product> [options]`

Lee <product>/agent-stack/deploy.yml, valida contra schema deploy/1 o deploy/2, e imprime el plan. Plan-only por diseño — la ejecución es workflow-driven (router deploy_product). ADR 009.

Cuando se ejecuta dentro de un workspace, aplica workspace.yml#deploy_overrides sobre el spec del stack (workspace gana por campo). Plaintext output marca componentes con (workspace override applied). Pasar --no-overrides para ver raw stack default.

`wsp secrets check <product> [options]`

Resuelve <product>/agent-stack/devvault.yml + ~/.devvault/.config.yml, reporta por entrada [ok]/[missing]/[unreadable]. Read-only, nunca imprime valores.

Cuando se ejecuta dentro de un workspace, aplica workspace.yml#devvault_overrides sobre el catálogo. Pasar --no-overrides para ver raw catalog defaults.

`wsp init [options]` — flags v1.1.0

Flag	Descripción
`--interactive` / `-i`	Wizard mode: lista templates, pide nombre, valida kebab-case, confirma producto templates.
`--yes` / `-y`	Auto-confirm para product templates (uso en CI/agents post-confirmación humana).

Templates de producto (<org>/agent-stack/templates/<X>-feature.yml) refusan scaffolding sin --yes ni --interactive (error WSP_020). Esto previene que un agente infiera template por nombre de carpeta y arrastre al usuario al flow del producto equivocado.

`wsp guide <topic>` (v1.1.0)

Imprime guías embebidas en el binario — diseñado para agentes que llegan a un workspace sin .agents/ cargado y necesitan orientación. Topics: init, onboard-product, deploy, secrets, discover. wsp guide (sin topic) lista los topics.

`wsp migrate-deploy <product>` (v1.1.0)

Lee <product>/agent-stack/deploy.yml desde el cache. Si está en deploy/1, lo reescribe a deploy/2 agregando targets_available con un solo elemento (el target actual; broaden manualmente). El patched file se deja para que el dev abra PR al stack repo.

`wsp templates / shortcuts / doctor / schema`

Comando	Output
`wsp templates [--json]`	Lista templates del registry. v1.1.0+: el output JSON incluye `requires_confirmation`, `composes_stacks`, `clones_repos`, `embeds_in_product_flow`. Plaintext flagga product templates con `[product]`.
`wsp shortcuts [--json]`	Lista shortcuts del registry.
`wsp doctor [--json]`	7 checks v1.1.0: git, gh, cache, registry, devvault_config, governance_mirror, stack_metadata_drift (nuevo: detecta edits locales a `.stack/<product>/` no sincronizados al stack repo).
`wsp schema <workspace\|awac\|lock\|deploy\|devvault>`	JSON Schema crudo. workspace devuelve `awac/2`, deploy devuelve `deploy/2`, lock devuelve `lock/2` (todos backward-compat con v1).
`wsp --agent-manifest`	Catálogo machine-readable de comandos para auto-discovery.

Códigos de error estructurados

Todos los errores llevan code (WSP_NNN), category, cause, remediation, opcionalmente details. Surface en plaintext y --json.

Code	Category	Cuándo
WSP_001	filesystem	workspace.yml no encontrado
WSP_002	schema	workspace.yml inválido
WSP_003	input	shortcut desconocido
WSP_004	network	clone falló
WSP_005	network	registry inalcanzable
WSP_006	filesystem	target dir no vacío
WSP_007	env	tool requerido faltante
WSP_008	input	template desconocido
WSP_011	schema	versión schema no soportada
WSP_012	network	gh repo list falló
WSP_013–WSP_016	varios	scaffold-stack errors
WSP_017–WSP_021	varios	scaffold-repo errors
WSP_022–WSP_024	varios	deploy errors
WSP_025–WSP_026	varios	secrets errors
WSP_018	schema	`deploy_overrides`/`devvault_overrides` requieren `schema: awac/2`
WSP_019	schema	override `target` fuera de `targets_available` del componente
WSP_020	input	template de producto requiere `--yes` o `--interactive`
WSP_021	filesystem	drift detectado en `.stack/<product>/` vs lockfile

Variables de entorno

Variable	Default	Descripción
`WSP_CACHE_DIR`	`~/.wsp/cache/`	Cache local de stacks clonados
`WSP_REGISTRY_REPO`	`<transversal-org>/agent-stack-core`	Override del registry (apuntá al registry de tu equipo)
`WSP_REGISTRY_BRANCH`	`main`	Branch del registry repo

Ver también

02-architecture.md — modelo conceptual.
03-manifest-reference.md — workspace.yml.
04-stack-reference.md — awac.yml + org_scaffold.
08-creating-new-stack.md — scaffold-stack en detalle.
14-deploy-and-secrets.md — deploy/2 + devvault/1 + workspace overrides + sus comandos.
15-stack-anatomy.md — qué se materializa al workspace (.stack/<product>/) vs assets compositables vs repos clonados (modelo mental para un workspace AWaC completo).

Referencia del CLI `wsp`

Roadmap del CLI

Instalación

Modo user (recomendado)

Modo dev (para hackear el CLI)

Filosofía: CLI agent-first

Comandos

wsp init <name> [options]

wsp bootstrap [options]

wsp sync [options]

wsp status [options]

wsp scaffold-stack <org> [options]

wsp scaffold-repo <full> --category <A|B|C|D|E> [options]

wsp governance check [options]

wsp audit <product> [options]

wsp deploy <product> [options]

wsp secrets check <product> [options]

wsp init [options] — flags v1.1.0

wsp guide <topic> (v1.1.0)

wsp migrate-deploy <product> (v1.1.0)

wsp templates / shortcuts / doctor / schema