NovoVeja como
FirstSales
Início/Tutoriais/Guia Rápido da CLI do FirstSales
Desenvolvedor e CLI

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.

8 min de leitura·Avançado·7 etapas
  1. 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. 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. 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. 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. 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. 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":"jane@acme.com","first_name":"Jane"}' --dry-run

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

# Verificação
firstsales contacts list --org ORG_ID --workspace WS_ID
  7. 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

Atalhos conquistados na prática que mantêm o aquecimento nos trilhos.

1

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.

2

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

3

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.

4

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.

Pronto para colocar isso em prática?

Comece seu teste do FirstSales e lance uma caixa de e-mail aquecida e autenticada em minutos.

Comece por $1
Todos os tutoriais