1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Ejecutar Claude Code mediante programación

6 

7> Utilice el Agent SDK para ejecutar Claude Code mediante programación desde la CLI, Python o TypeScript.

8 

9El [Agent SDK](/es/agent-sdk/overview) le proporciona las mismas herramientas, bucle de agente y gestión de contexto que potencian Claude Code. Está disponible como CLI para scripts e CI/CD, o como paquetes de [Python](/es/agent-sdk/python) y [TypeScript](/es/agent-sdk/typescript) para control programático completo.

10 

11<Note>

12 La CLI se llamaba anteriormente "modo sin interfaz". La bandera `-p` y todas las opciones de CLI funcionan de la misma manera.

13</Note>

14 

15Para ejecutar Claude Code mediante programación desde la CLI, pase `-p` con su indicación y cualquier [opción de CLI](/es/cli-reference):

16 

17```bash theme={null}

18claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

19```

20 

21Esta página cubre el uso del Agent SDK a través de la CLI (`claude -p`). Para los paquetes SDK de Python y TypeScript con salidas estructuradas, devoluciones de llamada de aprobación de herramientas y objetos de mensaje nativos, consulte la [documentación completa del Agent SDK](/es/agent-sdk/overview).

22 

23## Uso básico

24 

25Agregue la bandera `-p` (o `--print`) a cualquier comando `claude` para ejecutarlo de forma no interactiva. Todas las [opciones de CLI](/es/cli-reference) funcionan con `-p`, incluyendo:

26 

27* `--continue` para [continuar conversaciones](#continue-conversations)

28* `--allowedTools` para [aprobar herramientas automáticamente](#auto-approve-tools)

29* `--output-format` para [obtener salida estructurada](#get-structured-output)

30 

31Este ejemplo le pregunta a Claude sobre su base de código e imprime la respuesta:

32 

33```bash theme={null}

34claude -p "What does the auth module do?"

35```

36 

37### Comenzar más rápido con modo bare

38 

39Agregue `--bare` para reducir el tiempo de inicio omitiendo el descubrimiento automático de hooks, skills, plugins, servidores MCP, memoria automática y CLAUDE.md. Sin él, `claude -p` carga el mismo [contexto](/es/how-claude-code-works#the-context-window) que una sesión interactiva, incluyendo cualquier cosa configurada en el directorio de trabajo o `~/.claude`.

40 

41El modo bare es útil para CI y scripts donde necesita el mismo resultado en cada máquina. Un hook en el `~/.claude` de un compañero de equipo o un servidor MCP en el `.mcp.json` del proyecto no se ejecutarán, porque el modo bare nunca los lee. Solo las banderas que pasa explícitamente tienen efecto.

42 

43Este ejemplo ejecuta una tarea de resumen única en modo bare y aprueba previamente la herramienta Read para que la llamada se complete sin una solicitud de permiso:

44 

45```bash theme={null}

46claude --bare -p "Summarize this file" --allowedTools "Read"

47```

48 

49En modo bare Claude tiene acceso a las herramientas Bash, lectura de archivos y edición de archivos. Pase cualquier contexto que necesite con una bandera:

50 

51| Para cargar | Utilice |

52| ----------------------------------- | ------------------------------------------------------- |

53| Adiciones de indicación del sistema | `--append-system-prompt`, `--append-system-prompt-file` |

54| Configuración | `--settings <file-or-json>` |

55| Servidores MCP | `--mcp-config <file-or-json>` |

56| Agentes personalizados | `--agents <json>` |

57| Un directorio de plugin | `--plugin-dir <path>` |

58 

59El modo bare omite lecturas de OAuth y llavero. La autenticación de Anthropic debe provenir de `ANTHROPIC_API_KEY` o un `apiKeyHelper` en el JSON pasado a `--settings`. Bedrock, Vertex y Foundry utilizan sus credenciales de proveedor habituales.

60 

61<Note>

62 `--bare` es el modo recomendado para llamadas con scripts y SDK, y se convertirá en el predeterminado para `-p` en una versión futura.

63</Note>

64 

65## Ejemplos

66 

67Estos ejemplos destacan patrones comunes de CLI. Para CI y otras llamadas con scripts, agregue [`--bare`](#start-faster-with-bare-mode) para que no recojan lo que esté configurado localmente.

68 

69### Obtener salida estructurada

70 

71Utilice `--output-format` para controlar cómo se devuelven las respuestas:

72 

73* `text` (predeterminado): salida de texto sin formato

74* `json`: JSON estructurado con resultado, ID de sesión y metadatos

75* `stream-json`: JSON delimitado por saltos de línea para transmisión en tiempo real

76 

77Este ejemplo devuelve un resumen del proyecto como JSON con metadatos de sesión, con el resultado de texto en el campo `result`:

78 

79```bash theme={null}

80claude -p "Summarize this project" --output-format json

81```

82 

83Para obtener una salida que se ajuste a un esquema específico, utilice `--output-format json` con `--json-schema` y una definición de [JSON Schema](https://json-schema.org/). La respuesta incluye metadatos sobre la solicitud (ID de sesión, uso, etc.) con la salida estructurada en el campo `structured_output`.

84 

85Este ejemplo extrae nombres de funciones y los devuelve como una matriz de cadenas:

86 

87```bash theme={null}

88claude -p "Extract the main function names from auth.py" \

89 --output-format json \

90 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

91```

92 

93<Tip>

94 Utilice una herramienta como [jq](https://jqlang.github.io/jq/) para analizar la respuesta y extraer campos específicos:

95 

96 ```bash theme={null}

97 # Extract the text result

98 claude -p "Summarize this project" --output-format json | jq -r '.result'

99 

100 # Extract structured output

101 claude -p "Extract function names from auth.py" \

102 --output-format json \

103 --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \

104 | jq '.structured_output'

105 ```

106</Tip>

107 

108### Transmitir respuestas

109 

110Utilice `--output-format stream-json` con `--verbose` e `--include-partial-messages` para recibir tokens a medida que se generan. Cada línea es un objeto JSON que representa un evento:

111 

112```bash theme={null}

113claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

114```

115 

116El siguiente ejemplo utiliza [jq](https://jqlang.github.io/jq/) para filtrar deltas de texto y mostrar solo el texto transmitido. La bandera `-r` genera cadenas sin formato (sin comillas) y `-j` se une sin saltos de línea para que los tokens se transmitan continuamente:

117 

118```bash theme={null}

119claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \

120 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

121```

122 

123Cuando una solicitud de API falla con un error reintentable, Claude Code emite un evento `system/api_retry` antes de reintentar. Puede usar esto para mostrar el progreso del reintento o implementar lógica de retroceso personalizada.

124 

125| Campo | Tipo | Descripción |

126| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

127| `type` | `"system"` | tipo de mensaje |

128| `subtype` | `"api_retry"` | identifica esto como un evento de reintento |

129| `attempt` | entero | número de intento actual, comenzando en 1 |

130| `max_retries` | entero | reintentos totales permitidos |

131| `retry_delay_ms` | entero | milisegundos hasta el siguiente intento |

132| `error_status` | entero o nulo | código de estado HTTP, o `null` para errores de conexión sin respuesta HTTP |

133| `error` | cadena | categoría de error: `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `rate_limit`, `invalid_request`, `server_error`, `max_output_tokens`, o `unknown` |

134| `uuid` | cadena | identificador único del evento |

135| `session_id` | cadena | sesión a la que pertenece el evento |

136 

137El evento `system/init` informa metadatos de sesión incluyendo el modelo, herramientas, servidores MCP y plugins cargados. Es el primer evento en la transmisión a menos que [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/es/env-vars) esté configurado, en cuyo caso los eventos `plugin_install` lo preceden. Use los campos de plugin para fallar CI cuando un plugin no se cargó:

138 

139| Campo | Tipo | Descripción |

140| --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

141| `plugins` | matriz | plugins que se cargaron exitosamente, cada uno con `name` y `path` |

142| `plugin_errors` | matriz | errores de tiempo de carga de plugin como una versión de dependencia insatisfecha, cada uno con `plugin`, `type` y `message`. Los plugins afectados se degradan y están ausentes de `plugins`. La clave se omite cuando no hay errores |

143 

144Cuando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/es/env-vars) está configurado, Claude Code emite eventos `system/plugin_install` mientras los plugins del marketplace se instalan antes del primer turno. Use estos para mostrar el progreso de instalación en su propia interfaz de usuario.

145 

146| Campo | Tipo | Descripción |

147| ------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |

148| `type` | `"system"` | tipo de mensaje |

149| `subtype` | `"plugin_install"` | identifica esto como un evento de instalación de plugin |

150| `status` | `"started"`, `"installed"`, `"failed"`, o `"completed"` | `started` y `completed` enmarcan la instalación general; `installed` y `failed` reportan mercados individuales |

151| `name` | cadena, opcional | nombre del marketplace, presente en `installed` y `failed` |

152| `error` | cadena, opcional | mensaje de fallo, presente en `failed` |

153| `uuid` | cadena | identificador único del evento |

154| `session_id` | cadena | sesión a la que pertenece el evento |

155 

156Para transmisión programática con devoluciones de llamada y objetos de mensaje, consulte [Transmitir respuestas en tiempo real](/es/agent-sdk/streaming-output) en la documentación del Agent SDK.

157 

158### Aprobar herramientas automáticamente

159 

160Utilice `--allowedTools` para permitir que Claude use ciertas herramientas sin solicitar confirmación. Este ejemplo ejecuta un conjunto de pruebas y corrige fallos, permitiendo que Claude ejecute comandos Bash y lea/edite archivos sin pedir permiso:

161 

162```bash theme={null}

163claude -p "Run the test suite and fix any failures" \

164 --allowedTools "Bash,Read,Edit"

165```

166 

167Para establecer una línea base para toda la sesión en lugar de enumerar herramientas individuales, pase un [modo de permiso](/es/permission-modes). `dontAsk` deniega cualquier cosa que no esté en sus reglas `permissions.allow` o el [conjunto de comandos de solo lectura](/es/permissions#read-only-commands), que es útil para ejecuciones de CI bloqueadas. `acceptEdits` permite que Claude escriba archivos sin solicitar y también aprueba automáticamente comandos comunes del sistema de archivos como `mkdir`, `touch`, `mv` y `cp`. Otros comandos de shell y solicitudes de red aún necesitan una entrada `--allowedTools` o una regla `permissions.allow`, de lo contrario la ejecución se aborta cuando se intenta uno:

168 

169```bash theme={null}

170claude -p "Apply the lint fixes" --permission-mode acceptEdits

171```

172 

173### Crear una confirmación

174 

175Este ejemplo revisa los cambios preparados y crea una confirmación con un mensaje apropiado:

176 

177```bash theme={null}

178claude -p "Look at my staged changes and create an appropriate commit" \

179 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

180```

181 

182La bandera `--allowedTools` utiliza [sintaxis de regla de permiso](/es/settings#permission-rule-syntax). El ` *` final habilita la coincidencia de prefijo, por lo que `Bash(git diff *)` permite cualquier comando que comience con `git diff`. El espacio antes de `*` es importante: sin él, `Bash(git diff*)` también coincidiría con `git diff-index`.

183 

184<Note>

185 Las [skills](/es/skills) invocadas por el usuario como `/commit` y los [comandos integrados](/es/commands) solo están disponibles en modo interactivo. En modo `-p`, describa la tarea que desea realizar en su lugar.

186</Note>

187 

188### Personalizar el indicador del sistema

189 

190Utilice `--append-system-prompt` para agregar instrucciones mientras mantiene el comportamiento predeterminado de Claude Code. Este ejemplo canaliza un diff de PR a Claude e le indica que revise las vulnerabilidades de seguridad:

191 

192```bash theme={null}

193gh pr diff "$1" | claude -p \

194 --append-system-prompt "You are a security engineer. Review for vulnerabilities." \

195 --output-format json

196```

197 

198Consulte [banderas de indicador del sistema](/es/cli-reference#system-prompt-flags) para más opciones, incluyendo `--system-prompt` para reemplazar completamente el indicador predeterminado.

199 

200### Continuar conversaciones

201 

202Utilice `--continue` para continuar la conversación más reciente, o `--resume` con un ID de sesión para continuar una conversación específica. Este ejemplo ejecuta una revisión y luego envía indicaciones de seguimiento:

203 

204```bash theme={null}

205# First request

206claude -p "Review this codebase for performance issues"

207 

208# Continue the most recent conversation

209claude -p "Now focus on the database queries" --continue

210claude -p "Generate a summary of all issues found" --continue

211```

212 

213Si está ejecutando múltiples conversaciones, capture el ID de sesión para reanudar una específica:

214 

215```bash theme={null}

216session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')

217claude -p "Continue that review" --resume "$session_id"

218```

219 

220## Próximos pasos

221 

222* [Inicio rápido del Agent SDK](/es/agent-sdk/quickstart): construya su primer agente con Python o TypeScript

223* [Referencia de CLI](/es/cli-reference): todas las banderas y opciones de CLI

224* [GitHub Actions](/es/github-actions): utilice el Agent SDK en flujos de trabajo de GitHub

225* [GitLab CI/CD](/es/gitlab-ci-cd): utilice el Agent SDK en canalizaciones de GitLab