Pular para o conteúdo
NovoVeja como

Guia Rápido da CLI do FirstSales

Instale a CLI do FirstSales, autentique-se com uma chave de API e execute seus primeiros comandos seguros — whoami, descoberta de org/workspace, dry-run e idempotência.

Tutoriais
Desenvolvedor e CLI
min de leitura
8 min
etapas
7 · Avançado

  1. Instale a CLI

    A CLI do FirstSales é um pacote npm. Instale-a globalmente para obter o binário firstsales:

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

  2. Autentique-se

    Crie uma chave de API de desenvolvedor em Settings → API, depois passe a chave e a URL base para a CLI. A forma mais limpa é usar variáveis de ambiente:

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

  3. Verifique com whoami e doctor

    Antes de fazer qualquer coisa, confirme que a chave resolve para o contexto certo. whoami mostra seu usuário, org e workspace; doctor verifica sua configuração:

    firstsales whoami --json
firstsales doctor

  4. Entenda as flags globais

    Todo comando compartilha as mesmas flags (aprenda-as uma vez:

    • --org <id> / --workspace <id>) escopo de destino (a maioria dos comandos precisa de ambos).
    • --json (padrão) / --pretty (formato de saída.
    • --data '<json>' / --data-file <path>) corpo da requisição.
    • --idempotency-key <key> (retentativas seguras em criações.
    • --dry-run) pré-visualiza a requisição sem enviá-la.
    • --confirm (obrigatório para qualquer comando destrutivo (delete).
    • --api-key / --base-url / --profile) sobrescreve a autenticação por chamada.

  5. Descubra sua org e workspace

    A maioria dos comandos é vinculada a uma org e um workspace. Liste-os e depois reutilize os IDs:

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

  6. Faça sua primeira mutação com segurança

    Siga o ciclo de ouro: inspecione primeiro, mute deliberadamente, verifique depois. Pré-visualize com --dry-run, crie com uma chave de idempotência, depois releia para confirmar:

    # Pré-visualização: nenhuma escrita acontece
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"[email protected]","first_name":"Jane"}' --dry-run

# Criação real, de forma idempotente
firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"[email protected]","first_name":"Jane"}' \
  --idempotency-key jane-acme-2026-01

# Verificação
firstsales contacts list --org ORG_ID --workspace WS_ID

  7. Delete deliberadamente

    Comandos destrutivos se recusam a rodar sem --confirm: essa fricção é intencional para que um agente ou um comando digitado errado não consiga apagar dados por acidente:

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

Dicas de especialista

  • Inspecione primeiro, mute deliberadamente, verifique depois

    A CLI é construída em torno desse ciclo. Liste antes de mudar, faça --dry-run da mudança, execute, depois releia para confirmar. É mais lento de digitar e muito mais barato do que desfazer uma escrita ruim.

  • --json é para máquinas, --pretty é para você

    A saída é JSON compacto por padrão, para que scripts e agentes consigam parsear. Adicione --pretty quando um humano estiver lendo, mas mantenha --json em pipelines.

  • Nunca ecoe sua chave

    Passe a autenticação via FIRSTSALES_API_KEY ou um profile, não inline, onde ela vai parar no histórico do shell ou em logs. A CLI nunca imprime chaves cruas: não desfaça isso ecoando a variável de ambiente.

  • Chaves de idempotência são seguro grátis

    Qualquer criação que possa ser repetida deve levar --idempotency-key. Um comando repetido vira um no-op em vez de uma duplicata.

Perguntas frequentes

Como instalo a CLI?

npm install -g @firstsales.io/cli, o que te dá o binário firstsales. Ele mapeia diretamente para a API pública de desenvolvedor /api/v1.

Como funciona a autenticação?

Defina FIRSTSALES_API_KEY (e opcionalmente FIRSTSALES_BASE_URL) no seu ambiente, ou passe --api-key / --base-url por comando. Verifique com firstsales whoami --json.

Por que os comandos precisam de --org e --workspace?

Os recursos são vinculados a uma organização e a um workspace. Liste-os com organizations list e workspaces list --org ORG_ID, depois passe os dois IDs nos comandos vinculados.

O que --dry-run faz?

Imprime a requisição que a CLI enviaria sem realmente enviá-la: assim você confirma o corpo e o destino antes de uma mutação real.

Por que meu delete não roda?

Comandos destrutivos exigem a flag --confirm por design. Adicione --confirm quando tiver certeza: é a trava de segurança que impede exclusões acidentais.

A CLI é diferente da API?

É um wrapper fino sobre os mesmos endpoints públicos /api/v1. A CLI adiciona conveniência (autenticação centralizada, JSON estável, tratamento de idempotência e confirmação de operações destrutivas) para que agentes e scripts não precisem reimplementar isso.

Posso manter várias contas configuradas?

Sim: use --profile <name> para carregar um profile local salvo, ou sobrescreva --api-key/--base-url por comando para alternar entre orgs ou ambientes.

Desenvolvedor e CLI

Prospecção que continua quando você desconecta.Leads, emails, follow-ups e respostas, resolvidos.

Conecte caixas ilimitadas e deixe os agentes de IA encontrarem leads, escreverem cada email e fazerem follow-up. Ou envie seus próprios modelos no modo manual. A partir de $29/mês.

Comece seu teste de $1 Ver preços

$1 por 3 dias · Cancele quando quiser · Sem contrato

Instalar com IA

Seu agente de código configura a CLI e as skills do FirstSales para você.

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 ↗