← Volver al listado de tecnologías ← Índice de Claude Code

Cap 13: CLI Reference

2 de marzo de 2026 Por: Artiko

claude-codecliflagsheadless

CLI commands

Comando	Descripción
`claude`	Sesión interactiva
`claude "query"`	Sesión interactiva con prompt inicial
`claude -p "query"`	Query via SDK, luego exit (print mode)
`cat file \| claude -p "query"`	Procesa contenido por pipe
`claude -c`	Continúa la conversación más reciente del directorio
`claude -c -p "query"`	Continúa via SDK
`claude -r "<session>" "query"`	Resume sesión por ID o nombre
`claude update`	Update a la última versión
`claude install [version]`	Instalar/reinstalar binary nativo (`stable`, `latest`, o versión específica)
`claude auth login`	Sign in (`--email`, `--sso`, `--console`)
`claude auth logout`	Sign out
`claude auth status`	Status como JSON (`--text` legible). Exit 0 si logged in, 1 si no
`claude agents`	Abre agent view. `--cwd <path>` para filtrar
`claude attach <id>`	Attach a background session
`claude logs <id>`	Output reciente de background session
`claude stop <id>`	Stop background session (también `claude kill`)
`claude rm <id>`	Remover background session
`claude respawn <id>`	Restart sesión stopped con la conversación intacta. `--all` para todas
`claude mcp`	Configurar MCP servers
`claude mcp login <name>`	Autenticar un MCP server por OAuth desde la shell (v2.1.186+)
`claude mcp logout <name>`	Borrar las credenciales del server del keychain del sistema
`claude doctor`	Diagnóstico de la instalación y el entorno
`claude plugin install <p>@<marketplace>`	Instalar plugin. Alias: `claude plugins`
`claude project purge [path]`	Borrar todo el state local de un proyecto. Flags: `--dry-run`, `-y`, `--all`
`claude remote-control`	Server de Remote Control
`claude setup-token`	Generar OAuth token de larga duración para CI
`claude auto-mode defaults`	Print del classifier built-in como JSON
`claude ultrareview [target]`	Run ultrareview no-interactivo. `--json`, `--timeout <min>`

Sobre claude update / claude install: el método de instalación recomendado hoy es el instalador nativo, que se auto-actualiza en segundo plano, por lo que claude update rara vez hace falta.

curl -fsSL https://claude.ai/install.sh | bash              # macOS / Linux / WSL
irm https://claude.ai/install.ps1 | iex                     # PowerShell
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd

npm install -g @anthropic-ai/claude-code queda como opción avanzada. Homebrew, WinGet y los repos firmados apt/dnf/apk no se auto-actualizan salvo con CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.

Autenticación MCP desde la shell (v2.1.186+): claude mcp login <name> acepta --no-browser (imprime la URL, para entornos sin display, v2.1.191+), --callback-port y --client-id/--client-secret (o MCP_CLIENT_SECRET en CI). El secreto se guarda en el keychain del sistema, no en el config; claude mcp logout <name> lo borra.

CLI flags

Modelo y agente

Flag	Descripción
`--model <id>`	Modelo: alias o ID completo. Override `model` setting y `ANTHROPIC_MODEL`
`--advisor <model>`	Modelo advisor para la sesión
`--fallback-model <id>`	Fallback automático cuando el modelo default está overloaded (print mode)
`--effort <level>`	Set effort: `low`, `medium`, `high`, `xhigh`, `max`. Solo sesión, no persiste
`--agent <name>`	Agente para la sesión (override `agent` setting). Plugin: `<plugin>:<agent>`
`--agents '<json>'`	Define subagents dinámicamente. Mismos campos que frontmatter
`--teammate-mode <mode>`	`auto`, `in-process`, `tmux` para agent team display
`--forward-subagent-text`	Reenvía el texto de los subagentes a la salida

Alias de modelo vigentes: default, best, fable, sonnet, opus, haiku, sonnet[1m], opus[1m] y opusplan (usa opus en plan mode y sonnet en ejecución). Hoy opus → Opus 4.8 y sonnet → Sonnet 5. También acepta el ID completo (claude-opus-4-8, claude-sonnet-5, claude-fable-5): desde la generación 4.6 los IDs no llevan sufijo de fecha aunque siguen siendo snapshots pinneados.

Sesión

Flag	Descripción
`--continue`, `-c`	Carga la conversación más reciente del directorio
`--resume`, `-r [session]`	Resume por ID, nombre, o picker interactivo
`--fork-session`	Con `--resume`/`--continue`, crea nuevo session ID en vez de reusar
`--from-pr <pr>`	Resume sesiones linkeadas a un PR (número, URL GH/GitLab/Bitbucket)
`--name`, `-n <nombre>`	Display name de la sesión (visible en `/resume` y title)
`--session-id <uuid>`	Usar session ID específico (UUID válido)
`--no-session-persistence`	Print mode: no guardar la sesión a disk
`--bg "query"`	Iniciar como background agent y volver. Combiná con `--agent`
`--teleport`	Resumir web session en tu terminal
`--remote "task"`, `--cloud`	Crear nueva sesión en Claude Code on the web. `--cloud` es la forma equivalente
`--remote-control "name"`, `--rc`	Sesión interactiva con Remote Control

System prompt

Flag	Comportamiento
`--system-prompt "text"`	Reemplaza todo el prompt default
`--system-prompt-file <path>`	Reemplaza con contenido del archivo
`--append-system-prompt "text"`	Añade al prompt default
`--append-system-prompt-file <path>`	Añade contenido del archivo al default
`--exclude-dynamic-system-prompt-sections`	Mueve secciones per-machine al primer user message para mejorar prompt cache reuse

--system-prompt y --system-prompt-file son mutuamente exclusivas. Los append flags se combinan con cualquiera.

Permisos y tools

Flag	Descripción
`--permission-mode <mode>`	`default` (alias `manual` desde v2.1.200), `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. Override `defaultMode`
`--dangerously-skip-permissions`	Skip permission prompts. Equivalente a `--permission-mode bypassPermissions`
`--allow-dangerously-skip-permissions`	Agrega `bypassPermissions` al ciclo Shift+Tab sin iniciarlo
`--safe-mode`	Modo seguro de la sesión
`--allowedTools <patterns>`	Tools sin prompt (mismo syntax que permission rules)
`--disallowedTools <patterns>`	Tools removidos del contexto
`--tools <list>`	Restringir tools built-in. `""` para deshabilitar todos, `"default"` para todos, `"Bash,Edit,Read"`
`--permission-prompt-tool <mcp_tool>`	MCP tool para permission prompts en non-interactive
`--disable-slash-commands`	Deshabilitar skills/commands para la sesión

El modo default aparece etiquetado como Manual en la UI, y desde v2.1.200 manual es un alias aceptado por --permission-mode.

Restricciones de --dangerously-skip-permissions: en Linux y macOS Claude Code se niega a arrancar con esa flag bajo root/sudo (la verificación se omite dentro de un sandbox reconocido). Además, el clasificador de auto mode bloquea por defecto lanzar loops de agente autónomo sin aprobación humana ni sandbox, lo que incluye --dangerously-skip-permissions y --no-sandbox. La guía actual ya no recomienda el “safe YOLO mode”: los mecanismos vigentes son auto mode, allowlists vía /permissions y sandboxing OS-level vía /sandbox.

Directorios y settings

Flag	Descripción
`--add-dir <path>`	Agrega directorios de trabajo (solo file access; ver excepciones)
`--settings <path-or-json>`	Path o JSON inline que sobrescribe `settings.json` para la sesión
`--setting-sources <list>`	Coma-separated: `user`, `project`, `local`
`--worktree`, `-w [name\|#PR]`	Inicia en worktree aislado. Con `#123` o URL de PR, hace fetch
`--tmux`	Crea tmux session para el worktree. Requiere `--worktree`. `--tmux=classic` para tmux tradicional

Plugins

Flag	Descripción
`--plugin-dir <path>`	Cargar plugin desde dir o `.zip` para esta sesión. Repetible
`--plugin-url <url>`	Cargar plugin `.zip` desde URL. Repetible o space-separated

MCP

Flag	Descripción
`--mcp-config <path>`	Cargar MCP servers desde JSON (paths o strings space-separated)
`--strict-mcp-config`	Solo usar MCP servers de `--mcp-config`, ignorar otros
`--channels <list>`	(Preview) MCP servers para channel notifications
`--dangerously-load-development-channels`	Habilitar channels fuera del allowlist

Print mode (`-p`)

Flag	Descripción
`--print`, `-p`	Print response sin modo interactivo (SDK)
`--input-format <fmt>`	`text` o `stream-json`
`--output-format <fmt>`	`text`, `json`, `stream-json`. `stream-json` requiere `--verbose`
`--include-hook-events`	Incluir eventos de hook lifecycle (requiere `stream-json`)
`--include-partial-messages`	Eventos de streaming parcial (requiere `stream-json`)
`--replay-user-messages`	Re-emit user messages para acknowledgement
`--max-turns <n>`	Limitar turnos agentic. Exit con error al alcanzar
`--max-budget-usd <amount>`	Máximo a gastar antes de parar
`--json-schema '<schema>'`	Output JSON validado contra el schema
`--init`	Run Setup hooks con matcher `init` antes (print mode)
`--init-only`	Run Setup + SessionStart hooks y exit
`--maintenance`	Run Setup hooks con matcher `maintenance` (print mode)

Límites operativos del print mode: el stdin por pipe está limitado a 10MB desde v2.1.128, y una señal SIGTERM hace salir el proceso con código 143. Para recibir tokens parciales hay que combinar --output-format stream-json --verbose --include-partial-messages.

Bare mode (rápido)

--bare: skip auto-discovery de hooks, skills, plugins, MCP servers, auto memory y CLAUDE.md para que scripted calls inicien más rápido. Claude tiene acceso a Bash, Read, Edit. Setea CLAUDE_CODE_SIMPLE.

Es la opción recomendada para CI y para uso con el SDK, y está previsto que sea el default de -p en el futuro.

claude --bare -p "query"

Logging y debug

Flag	Descripción
`--debug [categories]`	Debug mode. Ej: `"api,hooks"`, `"!statsig,!file"`
`--debug-file <path>`	Logs a path específico (implica debug)
`--verbose`	Output turn-by-turn completo. Override `viewMode`

Otros

Flag	Descripción
`--ide`	Conectar a IDE al startup si hay exactamente uno disponible
`--chrome` / `--no-chrome`	Toggle Chrome integration
`--betas <list>`	Beta headers en API requests (solo API key users)
`--version`, `-v`	Versión
`--remote-control-session-name-prefix <prefix>`	Prefix para nombres auto-generados de Remote Control

Notas

claude --help no lista TODOS los flags; su ausencia no significa que el flag no exista.
Si tipiás mal un subcomando, Claude Code sugiere el más cercano: claude udpate → Did you mean claude update?.
Algunos flags son print-mode only (--max-turns, --max-budget-usd, --init, etc.).
Al correr no interactivamente con -p, la verificación de confianza (trust) de codebases y servidores MCP queda desactivada: un pipeline CI no conserva las mismas barreras de confianza que una sesión interactiva.

Cuándo usar replace vs append de system prompt

Append cuando Claude debe seguir siendo coding assistant + tus reglas extra: per-invocation instructions, output formatting, contexto de dominio para scripts -p. Preserva tool guidance, safety instructions y conventions.
Replace cuando la identidad o permission model difiere de Claude Code: agente no-coding en un pipeline sin humano. Dropea TODO el default, incluyendo tool guidance y safety — tomás vos esa responsabilidad.

Para personas persistentes shareables, usa output styles. Para convenciones del proyecto, usa CLAUDE.md.

Siguiente: Permisos y Sandbox