NuevoVer cómo
FirstSales
Inicio/Tutoriales/Guía rápida de la CLI de FirstSales
Desarrollador y CLI

Guía rápida de la CLI de FirstSales

Instala la CLI de FirstSales, autentícate con una clave de API y ejecuta tus primeros comandos seguros — whoami, descubrimiento de org/workspace, dry-run e idempotencia.

8 min de lectura·Avanzado·7 pasos
  1. 1

    Instala la CLI

    La CLI de FirstSales es un paquete de npm. Instálala globalmente para obtener el binario firstsales:

    npm install -g @firstsales.io/cli
firstsales --version
  2. 2

    Autentícate

    Crea una Developer API key en Settings → API, y luego dale a la CLI la clave y la URL base. La forma más limpia es mediante variables de entorno:

    export FIRSTSALES_API_KEY="fs-key-..."
export FIRSTSALES_BASE_URL="https://api.app.firstsales.io"
  3. 3

    Verifica con whoami y doctor

    Antes de hacer nada, confirma que la clave resuelve al contexto correcto. whoami muestra tu usuario, org y workspace; doctor revisa tu configuración:

    firstsales whoami --json
firstsales doctor
  4. 4

    Entiende las flags globales

    Todos los comandos comparten las mismas flags — apréndelas una vez:

    • --org <id> / --workspace <id> — alcance objetivo (la mayoría de comandos necesitan ambos).
    • --json (predeterminado) / --pretty — formato de salida.
    • --data '<json>' / --data-file <path> — cuerpo de la solicitud.
    • --idempotency-key <key> — reintentos seguros en creaciones.
    • --dry-run — previsualiza la solicitud sin enviarla.
    • --confirm — requerido para cualquier comando destructivo (delete).
    • --api-key / --base-url / --profile — sobrescribe la autenticación por llamada.
  5. 5

    Descubre tu org y tu workspace

    La mayoría de los comandos están acotados a una org y un workspace. Lístalos, y luego reutiliza los IDs:

    firstsales organizations list
firstsales workspaces list --org ORG_ID
firstsales campaigns list --org ORG_ID --workspace WS_ID
  6. 6

    Haz tu primera mutación segura

    Sigue el ciclo de oro: inspect first, mutate deliberately, verify after. Previsualiza con --dry-run, luego crea con una idempotency key, y luego vuelve a leer para confirmar:

    # Preview — no write happens
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' --dry-run

# Create for real, idempotently
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"jane@acme.com","first_name":"Jane"}' \
  --idempotency-key jane-acme-2026-01

# Verify
firstsales contacts list --org ORG_ID --workspace WS_ID
  7. 7

    Elimina de forma deliberada

    Los comandos destructivos se niegan a ejecutarse sin --confirm — esto es fricción intencional para que un agente o un comando escrito por error no pueda borrar datos por accidente:

    firstsales contacts delete --org ORG_ID --workspace WS_ID \
  --contact CONTACT_ID --confirm

Consejos de experto

Atajos aprendidos a fuerza de experiencia para mantener el precalentamiento en curso.

1

Inspecciona primero, muta con deliberación, verifica después

La CLI está construida alrededor de este ciclo. Lista antes de cambiar, haz --dry-run del cambio, ejecútalo, y luego vuelve a leer para confirmar. Es más lento de escribir y mucho más barato que deshacer una escritura errónea.

2

--json es para máquinas, --pretty es para ti

La salida por defecto es JSON compacto para que los scripts y agentes puedan analizarla. Añade --pretty cuando un humano esté leyendo, pero mantén --json en los pipelines.

3

Nunca imprimas tu clave

Pasa la autenticación mediante FIRSTSALES_API_KEY o un profile, no en línea, donde termina en el historial de la shell o en logs. La CLI nunca imprime claves en crudo — no lo deshagas haciendo echo de la variable de entorno.

4

Las idempotency keys son un seguro gratuito

Cualquier creación que se pueda reintentar debería llevar --idempotency-key. Un comando reproducido se convierte en un no-op en vez de un duplicado.

Preguntas frecuentes

¿Cómo instalo la CLI?

npm install -g @firstsales.io/cli, lo que te da el binario firstsales. Se mapea directamente a la Developer API pública /api/v1.

¿Cómo funciona la autenticación?

Configura FIRSTSALES_API_KEY (y opcionalmente FIRSTSALES_BASE_URL) en tu entorno, o pasa --api-key / --base-url por comando. Verifica con firstsales whoami --json.

¿Por qué los comandos necesitan --org y --workspace?

Los recursos están acotados a una organización y un workspace. Lístalos con organizations list y workspaces list --org ORG_ID, y luego pasa ambos IDs en los comandos acotados.

¿Qué hace --dry-run?

Imprime la solicitud que la CLI enviaría sin enviarla realmente — así puedes confirmar el cuerpo y el destino antes de una mutación real.

¿Por qué no se ejecuta mi delete?

Los comandos destructivos requieren la flag --confirm por diseño. Añade --confirm cuando estés seguro — es el seguro que evita eliminaciones accidentales.

¿Es la CLI distinta de la API?

Es una envoltura fina sobre los mismos endpoints públicos /api/v1. La CLI añade comodidad — autenticación centralizada, JSON estable, manejo de idempotencia y confirmación de operaciones destructivas — para que los agentes y scripts no tengan que reimplementarlo.

¿Puedo mantener varias cuentas configuradas?

Sí — usa --profile <name> para cargar un profile local guardado, o sobrescribe --api-key/--base-url por comando para cambiar entre orgs o entornos.

¿Listo para ponerlo en práctica?

Comienza tu prueba de FirstSales y lanza un buzón precalentado y autenticado en minutos.

Empieza por $1
Todos los tutoriales