Por qué usar la CLI con Claude Code
Claude Code tiene acceso a shell, así que debería operar FirstSales a través de la CLI, no de HTTP en crudo. La CLI centraliza la autenticación, devuelve JSON estable que el agente puede analizar, maneja las cabeceras de idempotencia, y obliga a confirmar en operaciones destructivas: todo lo que de otro modo tendrías que indicarle al agente que hiciera correctamente cada vez.
Regla general de la documentación: los agentes deberían preferir la CLI cuando existe acceso a shell.
Instala y expón la clave
Instala la CLI una vez, y dale a Claude Code la clave a través del entorno para que nunca aparezca en un prompt o en una transcripción:
npm install -g @firstsales.io/cli export FIRSTSALES_API_KEY="fs-key-..." # set in your shell, not in the chatDale al agente sus reglas de operación
Pega un breve contrato de operación en Claude Code (o en un archivo de reglas del proyecto) para que se comporte de forma segura:
- Empieza cada sesión con
firstsales whoami --json; confirma org y workspace antes de actuar. - Inspecciona primero, muta con deliberación, verifica después.
- Usa
--idempotency-keyen cualquier creación que se pueda reintentar. - Usa
--confirmsolo para una eliminación intencional que el usuario haya pedido. - Nunca imprimas claves de API en crudo.
- Empieza cada sesión con
La exploración de solo lectura siempre es segura
Anima al agente a explorar libremente con comandos list/get: no pueden dañar nada:
firstsales campaigns list --org ORG_ID --workspace WS_ID --json firstsales contacts list --org ORG_ID --workspace WS_ID --json firstsales billing overview --org ORG_ID --jsonMutaciones: previsualizar, actuar, verificar
Para cualquier cosa que escriba, haz que Claude Code siga el ciclo completo:
--dry-run, luego la llamada real con una idempotency key, y luego una relectura:firstsales contacts create --org ORG_ID --workspace WS_ID \ --data '{"email":"[email protected]","first_name":"Sam"}' --dry-run firstsales contacts create --org ORG_ID --workspace WS_ID \ --data '{"email":"[email protected]","first_name":"Sam"}' \ --idempotency-key sam-acme-2026-01 firstsales contacts list --org ORG_ID --workspace WS_ID --jsonAprueba o rechaza borradores de IA desde la terminal
Un ciclo útil con Claude Code: revisar respuestas escritas por IA pendientes y actuar sobre ellas sin abrir la app. Lista los hilos, lee uno, y luego aprueba o rechaza el borrador:
firstsales inbox threads --org ORG_ID --workspace WS_ID firstsales inbox thread --org ORG_ID --workspace WS_ID --thread THREAD_ID firstsales inbox approve-draft --org ORG_ID --workspace WS_ID \ --email EMAIL_ID --idempotency-key approve-EMAIL_IDRespeta la superficie pública
Indica al agente que se mantenga dentro de los comandos públicos de la CLI. Si un comando devuelve
unsupported_operation, debe detenerse y reportarlo: no intentar llamar a rutas privadas de la app, callbacks de proveedores, píxeles de seguimiento, gestores de baja, o endpoints internos de cron para forzar el resultado.
Consejos de experto
Pon las reglas de operación en un archivo de reglas del proyecto
En lugar de repegar el contrato de seguridad cada sesión, colócalo en las reglas de proyecto de Claude Code para que cada ejecución empiece con whoami y el ciclo inspeccionar-mutar-verificar.
La clave en el entorno, nunca en el chat
Exporta FIRSTSALES_API_KEY en la shell donde corre Claude Code. Si la clave está en un prompt, está en la transcripción: la CLI la mantiene fuera de la salida, no la vuelvas a meter ahí.
Déjalo leer libremente, condiciona las escrituras
Los comandos list/get/analytics son seguros de ejecutar sin supervisión. Reserva tu revisión para cualquier cosa con create/update/delete o --confirm.
unsupported_operation significa detenerse
Entrena al agente para tratar unsupported_operation como un muro, no como un rompecabezas. La CLI pública es toda la superficie permitida; no hay atajo ingenioso que valga el riesgo.
Preguntas frecuentes
¿Debería Claude Code usar la CLI o la API?
La CLI. Como Claude Code tiene acceso a shell, la CLI es la opción preferida: centraliza la autenticación, emite JSON estable, y aplica la idempotencia y la confirmación de operaciones destructivas para que el agente no tenga que reimplementarlas.
¿Cómo mantengo mi clave de API fuera de la transcripción?
Exporta FIRSTSALES_API_KEY en la shell antes de iniciar Claude Code, e indícale que nunca imprima claves en crudo. La CLI lee la variable de entorno y nunca la repite en la salida.
¿Cuál es el flujo seguro para hacer cambios?
Verifica la identidad con whoami, confirma org/workspace, inspecciona el estado actual, haz el cambio mínimo con --dry-run y luego con --idempotency-key, usa --confirm solo para eliminaciones intencionales, y vuelve a leer para validar.
¿Puede gestionar la bandeja de entrada?
Sí: inbox threads, inbox thread, y inbox approve-draft / reject-draft permiten que Claude Code clasifique y actúe sobre respuestas escritas por IA desde la terminal.
¿Qué pasa si un comando no está soportado?
Si la CLI devuelve unsupported_operation, el agente debe detenerse y reportarlo. No debe recurrir a rutas privadas de la app, callbacks, píxeles, o endpoints de cron: esos están prohibidos y romperán algo.
¿Cómo evito eliminaciones accidentales?
Los comandos destructivos requieren --confirm. Mientras el agente solo añada --confirm para eliminaciones que el usuario haya pedido explícitamente, no puede ocurrir un borrado accidental en silencio.