Saltar al contenido
NuevoVer cómo

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.

Tutoriales
Desarrollador y CLI
min de lectura
8 min
pasos
7 · Avanzado

  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. 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. 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. 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. 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. 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":"[email protected]","first_name":"Jane"}' --dry-run

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

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

  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

  • 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.

  • --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.

  • 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.

  • 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.

Desarrollador y CLI

Prospección que sigue cuando te desconectas.Leads, emails, seguimientos y respuestas, resueltos.

Conecta buzones ilimitados y deja que los agentes de IA busquen leads, escriban cada email y hagan seguimiento. O envía tus propias plantillas en modo manual. Desde $29/mes.

Empieza tu prueba de $1 Ver precios

$1 por 3 días · Cancela cuando quieras · Sin contrato

Instalar con IA

Tu agente de código configura la CLI y las skills de FirstSales por ti.

Prompt para Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗