@roasted/cli

Referência completa da CLI

Uma estrutura de busca por emprego não interativa para pessoas e agentes. Comece com um currículo de origem, crie um kit personalizado para cada vaga, renderize o PDF e registre a candidatura.

Instale e comece

Instale o pacote global e siga o caminho ideal abaixo. O executável é roasted. Ele inclui as configurações de conexão de produção, então nenhuma configuração de ambiente é necessária.

terminal

npm i -g @roasted/cli
roasted login
roasted cv push ./resume.yaml --name "Backend Engineer"
roasted apply plan
roasted apply create --cv "Backend Engineer" --jd-file ./jd.txt
roasted apply pdf <applyKitId> --out resume.pdf
roasted app add --from-kit <applyKitId>

Orientação para agentes

Todo comando aceita --json, toda entrada pode vir de flags ou do stdin, e nada solicita informações após a invocação. Os agentes devem analisar o stdout e ramificar com base em códigos de erro estáveis em vez do texto da mensagem.

O sucesso sai com 0. Qualquer erro sai com 1 e retorna um objeto de erro no modo JSON.
apply create --no-wait retorna o ID do kit de candidatura imediatamente para paralelização e consulta posterior.
apply create --watch transmite uma linha NDJSON por fase antes do resultado final.
ROASTED_API_KEY sobrepõe os perfis armazenados para execuções headless efêmeras.
--profile ou ROASTED_PROFILE seleciona uma conta nomeada sem alterar o estado global.

Autenticação e perfis

O login no navegador usa PKCE. As sessões ficam em ~/.roasted/profiles.json com permissões apenas para o proprietário onde houver suporte. A ordem de seleção é ROASTED_API_KEY, --profile, ROASTED_PROFILE e, por fim, o perfil ativo. As sessões OAuth são renovadas automaticamente. Os perfis de chave de API trocam novamente sua chave armazenada quando uma sessão expira.

terminal

roasted login --profile primary
roasted login --profile second --api-key -
roasted accounts
roasted switch second
roasted cv list --profile primary

Chaves de API

As chaves pessoais começam com rmt_pat_ e são exibidas uma única vez. Apenas o hash delas é armazenado pelo servidor. Use --api-key - para ler uma chave do stdin e mantê-la fora do histórico do shell.

terminal

roasted keys create ci-runner --ttl never
roasted login --api-key rmt_pat_...
ROASTED_API_KEY=rmt_pat_... roasted cv list

Referência de comandos

Autenticação e contas

Comando	Finalidade
roasted login [--api-key <key\|->]	Entre via PKCE no navegador ou com uma chave de API.
roasted accounts	Liste os perfis e mostre o ativo.
roasted switch <name>	Torne ativo um perfil nomeado.
roasted whoami	Mostre a identidade atual, o papel, o código de indicação e o perfil.
roasted logout [--all]	Remova o perfil selecionado ou todos os perfis.
roasted keys create <name> [--ttl <ttl>]	Crie uma chave de API pessoal com expiração de 30d, 90d, 1y ou nunca.
roasted keys list	Liste as chaves com status e último uso.
roasted keys revoke <id\|name>	Revogue uma chave por ID ou nome.

Currículos

Comando	Finalidade
roasted cv list	Liste os currículos da conta, do mais novo ao mais antigo.
roasted cv search <query>	Filtre currículos por nome.
roasted cv pull <id\|name> [--out file]	Baixe o YAML do currículo para o stdout ou um arquivo.
roasted cv push <file> [--id <id>] [--name <name>]	Crie ou atualize um currículo a partir de YAML ou JSON validado.

Kits de candidatura

Comando	Finalidade
roasted apply plan	Mostre o plano, o saldo de créditos e os custos dos kits.
roasted apply create --cv <id\|name>	Gere um currículo e uma carta de apresentação personalizados. Isso gasta créditos.
roasted apply list	Liste os kits de candidatura, do mais novo ao mais antigo.
roasted apply get <id>	Leia o status e os resultados. Adicione --pages para renderizar e contar as páginas.
roasted apply cv <kitId> [--out file]	Baixe o YAML do currículo personalizado.
roasted apply push <kitId> <file.yaml>	Valide e envie um currículo personalizado editado à mão.
roasted apply pdf <id>	Renderize localmente a cópia do servidor do currículo personalizado.
roasted apply shrink <id>	Ajuste o currículo personalizado para uma página. Isso pode gastar um crédito.

Rastreador de candidaturas

Comando	Finalidade
roasted app list [--status <status>]	Liste as candidaturas, opcionalmente filtradas por status.
roasted app get <id>	Leia um registro completo de candidatura.
roasted app add	Crie uma candidatura manualmente ou a partir de um kit de candidatura pronto.
roasted app status <id> <status>	Mude o status e, opcionalmente, defina um resultado de encerramento ou uma nota.
roasted app note <id> <text>	Defina notas. Um valor vazio as apaga.
roasted app rm <id>	Exclua uma candidatura.

Fluxo do kit de candidatura

O comando create espera por padrão e depois imprime o resultado e a URL do painel. Use get para consultas baratas e adicione --pages apenas quando a contagem de páginas for necessária. As referências de currículo são resolvidas por ID exato e depois por uma correspondência de nome única e sem diferenciação de maiúsculas e minúsculas.

terminal

roasted cv list
roasted apply plan
roasted apply create --cv "Backend Engineer" --jd-file ./jd.txt \
  --intensity smart --tone professional --length concise
roasted apply get <id> --pages --json
roasted apply cv <id> --out tailored.yaml
roasted apply push <id> tailored.yaml
roasted apply pdf <id> --out resume.pdf
roasted apply shrink <id>

Descrição da vaga e flags de moldagem

Edite o currículo personalizado com segurança

Baixe com apply cv, edite localmente e depois envie com apply push antes de renderizar. A cópia do servidor é canônica. Se você pular o push, o apply pdf renderiza novamente a versão antiga do servidor e ignora as alterações locais.

PDF e ajuste para uma página

O apply pdf usa o binário local typst. Sem ele, o comando sai com sucesso com um link do painel e uma dica de instalação. O apply shrink verifica a contagem de páginas quando um renderizador está disponível, para sem gastar se o currículo já couber e salva o YAML revisado de volta no kit.

O que custa dinheiro

Grátis: login, gerenciamento de contas e chaves, comandos de currículo, verificações de plano e leituras do rastreador.
Hunter Pass mais créditos: apply create e apply shrink. Uma verificação prévia rejeita planos gratuitos ou saldos insuficientes antes da geração.
Hunter Pass: criar entradas no rastreador, incluindo entradas derivadas de um kit de candidatura. Status, notas, exclusão e leituras não são restritos.
Falhas de geração são reembolsadas pelo backend. A CLI nunca altera saldos por conta própria.

Playbooks de ponta a ponta

Pipeline em lote

Envie um currículo de origem, inicie um kit por descrição de vaga salva sem esperar, consulte cada ID, renderize os PDFs e registre as candidaturas que foram realmente enviadas.

shell

roasted cv push ./canon-resume.yaml --name "Backend Engineer" --json
CV=$(roasted cv list --json | jq -r '.cvs[] | select(.name=="Backend Engineer") | .id')
for jd in jds/*.txt; do
  roasted apply create --cv "$CV" --jd-file "$jd" --no-wait --json
done > kits.ndjson
jq -r '.applyKitId' kits.ndjson | while read -r id; do
  while :; do
    kit=$(roasted apply get "$id" --json) || { printf 'Retrying kit %s
' "$id" >&2; sleep 2; continue; }
    status=$(printf '%s' "$kit" | jq -r '.status')
    case "$status" in
      ready) break ;;
      generating) sleep 2 ;;
      *) printf 'Kit %s stopped with status: %s
' "$id" "$status" >&2; continue 2 ;;
    esac
  done
  roasted apply pdf "$id" --out "out/$id.pdf" --json
  roasted app add --from-kit "$id" --status applied --json
done

Candidatura conduzida por agente

Para o trabalho um de cada vez, deixe o agente criar e inspecionar o kit, copiar a carta de apresentação e mover o registro do rastreador pelo fluxo real de status da candidatura.

shell

roasted apply create --cv "QA Engineer" --jd-file ./jd.txt \
  --cv-lang en --cl-lang en --intensity smart --json
ID=<applyKitId>
roasted apply get "$ID" --pages --json
roasted apply shrink "$ID" --json
roasted apply get "$ID" --json | jq -r '.coverLetter' > cover-letter.txt
roasted app add --from-kit "$ID" --status saved --json
roasted app status <appId> applied --json
roasted app status <appId> interviewing --json
roasted app status <appId> closed --outcome offer --json

Esquemas de saída JSON

Os exemplos abaixo mostram as estruturas críticas para a orquestração. Campos anuláveis permanecem presentes. No modo watch, os objetos de progresso são emitidos um por linha antes do resultado final.

whoami

{ "email": string|null, "role": string|null, "refCode": string|null,
  "userId": string, "profile": string|null,
  "auth": "oauth"|"api_key"|"env_api_key" }

accounts

{ "active": string|null, "activeSource": string, "envApiKey": boolean,
  "accounts": [{ "name": string, "type": "oauth"|"api_key",
    "email": string|null, "apiKeyMasked": string|null, "active": boolean }] }

keys create

{ "id": string, "name": string, "key": string, "masked": string,
  "status": "active", "createdAt": string, "expiresAt": string|null,
  "lastUsedAt": null, "revokedAt": null }

keys list

{ "keys": [{ "id": string, "name": string, "masked": string,
  "status": "active"|"revoked"|"expired", "createdAt": string,
  "expiresAt": string|null, "lastUsedAt": string|null,
  "revokedAt": string|null }] }

cv list / cv search

{ "cvs": [{ "id": string, "name": string|null, "updatedAt": string }] }

cv pull

{ "id": string, "name": string|null, "yaml": string }

cv push

{ "id": string, "name": string|null, "created": boolean,
  "warnings": string[], "dashboardUrl": string }

apply plan

{ "plan": string, "credits": number, "cost": number,
  "premiumCost": number, "canAfford": boolean }

apply create --no-wait

{ "applyKitId": string }

apply create --watch

{ "phase": string, "at": string }

apply create / apply get

{ "id": string, "createdAt": string,
  "status": "generating"|"ready"|"failed", "progressStep": string|null,
  "jobTitle": string|null, "company": string|null, "location": string|null,
  "seniority": string|null, "salaryRange": string|null, "techStack": string[],
  "keyRequirements": string[], "niceToHave": string[], "deadline": string|null,
  "intensity": string|null, "tone": string|null, "length": string|null,
  "coverLetter": string|null, "includeCoverLetter": boolean, "premium": boolean,
  "sourceCvFileId": string|null, "tailoredFileId": string|null,
  "failureReason": string|null, "generatedAt": string|null,
  "dashboardUrl": string, "pageCount": number|null }

apply list

{ "kits": [{ "id": string, "createdAt": string, "status": string|null,
  "jobTitle": string|null, "company": string|null, "intensity": string|null,
  "tone": string|null, "length": string|null }] }

apply pdf

{ "applyKitId": string, "pageCount": number|null, "out": string|null,
  "dashboardUrl": string, "hint"?: string }

apply shrink

{ "applyKitId": string, "tailoredFileId"?: string,
  "pageCountBefore": number|null, "pageCountAfter": number|null,
  "changed": boolean, "dashboardUrl": string }

app list

{ "applications": [{ "id": string, "status": string|null,
  "outcome": string|null, "company": string|null, "position": string|null,
  "location": string|null, "source": string|null, "appliedAt": string|null,
  "createdAt": string, "updatedAt": string }] }

app get / add / save / status / note

{ "id": string, "status": string|null, "outcome": string|null,
  "company": string|null, "position": string|null, "location": string|null,
  "salaryRange": string|null, "seniority": string|null, "sourceUrl": string|null,
  "contactPerson": string|null, "contactEmail": string|null, "deadline": string|null,
  "cvFileId": string|null, "applyKitId": string|null, "appliedAt": string|null,
  "source": string|null, "jdText": string|null, "coverLetter": string|null,
  "notes": string|null, "techStack": string[], "keyRequirements": string[],
  "niceToHave": string[], "createdAt": string, "updatedAt": string,
  "dashboardUrl": string }

app rm

{ "id": string, "deleted": true }

error

{ "error": { "code": string, "message": string } }

Os comandos de listagem envolvem as linhas em arrays cvs, kits, applications ou keys. Os comandos de detalhe retornam o registro completo, incluindo metadados anuláveis da vaga, timestamps, IDs de arquivos vinculados, conteúdo de origem e a URL do painel.

Códigos de saída e catálogo de erros

Todos os comandos saem com 0 em caso de sucesso e 1 em qualquer erro. No modo JSON, inspecione error.code. Os códigos de erro do backend vindos da geração e do encolhimento são repassados sem alteração. PAID_PLAN_REQUIRED em uma conta gratuita é comportamento esperado, não um defeito: kits de candidatura e novas entradas no rastreador exigem um Hunter Pass ativo, e assinar resolve o código.

Autenticação e perfis: NO_SESSION, SESSION_EXPIRED, AUTH_UNAVAILABLE, BAD_PROFILE, PROFILE_NOT_FOUND, PROFILE_STORE_CORRUPT, API_KEY_INVALID, API_KEY_EXCHANGE_FAILED, BAD_KEY_NAME, BAD_TTL, KEY_NOT_FOUND, KEY_AMBIGUOUS.
Currículos e kits de candidatura: CV_NOT_FOUND, CV_AMBIGUOUS, BAD_CV_YAML, FILE_NOT_FOUND, JD_MISSING, JD_CONFLICT, JD_TOO_SHORT, BAD_INTENSITY, BAD_TONE, BAD_LENGTH, BAD_FORMALITY, PAID_PLAN_REQUIRED, INSUFFICIENT_CREDITS, NOT_FOUND, NO_TAILORED_FILE, NO_YAML, NO_CV_CONTENT, TYPST_COMPILE_FAILED, KIT_TIMEOUT.
Rastreador: BAD_STATUS, BAD_OUTCOME, OUTCOME_REQUIRES_CLOSED, APP_EMPTY, APP_ARG_CONFLICT, PAID_PLAN_REQUIRED, KIT_NOT_READY, NOT_FOUND.