Skip to content

@roasted/cli

Referencia completa de la CLI

Un arnés de búsqueda de empleo no interactivo para personas y agentes. Empieza con un currículum fuente, crea un kit personalizado para cada empleo, renderiza el PDF y registra la postulación.

Instala y empieza

Instala el paquete global y sigue la ruta ideal de abajo. El ejecutable es roasted. Incluye la configuración de conexión de producción, así que no se requiere configurar el entorno.

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>

Orientación para agentes

Cada comando acepta --json, cada entrada puede venir de flags o de stdin, y nada solicita datos tras la invocación. Los agentes deben analizar stdout y ramificar según códigos de error estables en lugar del texto del mensaje.

  • El éxito sale con 0. Cualquier error sale con 1 y devuelve un objeto de error en modo JSON.
  • apply create --no-wait devuelve el ID del kit de postulación de inmediato para fan-out y sondeo posterior.
  • apply create --watch transmite una línea NDJSON por fase antes del resultado final.
  • ROASTED_API_KEY anula los perfiles almacenados para ejecuciones efímeras sin interfaz.
  • --profile o ROASTED_PROFILE selecciona una cuenta con nombre sin cambiar el estado global.

Autenticación y perfiles

El inicio de sesión en el navegador usa PKCE. Las sesiones viven en ~/.roasted/profiles.json con permisos solo para el propietario donde se admite. El orden de selección es ROASTED_API_KEY, --profile, ROASTED_PROFILE y luego el perfil activo. Las sesiones OAuth se renuevan automáticamente. Los perfiles con clave de API vuelven a canjear su clave almacenada cuando una sesión caduca.

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

Claves de API

Las claves personales empiezan con rmt_pat_ y se muestran una sola vez. El servidor solo almacena su hash. Usa --api-key - para leer una clave desde stdin y mantenerla fuera del historial del shell.

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

Referencia de comandos

Autenticación y cuentas

ComandoPropósito
roasted login [--api-key <key|->]Inicia sesión mediante PKCE en el navegador o una clave de API.
roasted accountsLista los perfiles y muestra el activo.
roasted switch <name>Activa un perfil con nombre.
roasted whoamiMuestra la identidad actual, el rol, el código de referido y el perfil.
roasted logout [--all]Elimina el perfil seleccionado o todos los perfiles.
roasted keys create <name> [--ttl <ttl>]Crea una clave de API personal con caducidad de 30d, 90d, 1y o nunca.
roasted keys listLista las claves con su estado y último uso.
roasted keys revoke <id|name>Revoca una clave por ID o nombre.

Currículums

ComandoPropósito
roasted cv listLista los currículums de la cuenta, del más reciente al más antiguo.
roasted cv search <query>Filtra los currículums por nombre.
roasted cv pull <id|name> [--out file]Descarga el YAML del currículum a stdout o a un archivo.
roasted cv push <file> [--id <id>] [--name <name>]Crea o actualiza un currículum a partir de YAML o JSON validados.

Kits de postulación

ComandoPropósito
roasted apply planMuestra el plan, el saldo de créditos y los costos de los kits.
roasted apply create --cv <id|name>Genera un currículum y una carta de presentación personalizados. Esto consume créditos.
roasted apply listLista los kits de postulación, del más reciente al más antiguo.
roasted apply get <id>Lee el estado y los resultados. Añade --pages para renderizar y contar las páginas.
roasted apply cv <kitId> [--out file]Descarga el YAML del currículum personalizado.
roasted apply push <kitId> <file.yaml>Valida y sube un currículum personalizado editado a mano.
roasted apply pdf <id>Renderiza localmente la copia del servidor del currículum personalizado.
roasted apply shrink <id>Ajusta el currículum personalizado a una página. Esto puede consumir un crédito.

Seguimiento de postulaciones

ComandoPropósito
roasted app list [--status <status>]Lista las postulaciones, opcionalmente filtradas por estado.
roasted app get <id>Lee un registro completo de postulación.
roasted app addCrea una postulación manualmente o a partir de un kit de postulación listo.
roasted app status <id> <status>Cambia el estado y opcionalmente establece un resultado de cierre o una nota.
roasted app note <id> <text>Establece notas. Un valor vacío las borra.
roasted app rm <id>Elimina una postulación.

Flujo del kit de postulación

El comando create espera de forma predeterminada y luego imprime el resultado y la URL del panel. Usa get para un sondeo económico y añade --pages solo cuando se necesite el conteo de páginas. Las referencias a currículums se resuelven por ID exacto y luego por una coincidencia única de nombre sin distinción de mayú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>

Descripción de empleo y flags de moldeado

Proporciona exactamente uno de --jd-file, --jd o --jd-stdin. El texto de menos de 50 caracteres se rechaza. Moldea el resultado con intensity safe|smart|bold, tone auto|professional|confident|conversational, length concise|standard|detailed, formality formal|neutral|casual, flags de language e instruction, --premium y el conmutador de la carta de presentación. Los valores no válidos fallan antes de gastar créditos.

Edita el currículum personalizado con seguridad

Descarga con apply cv, edita localmente y luego sube con apply push antes de renderizar. La copia del servidor es la canónica. Si te saltas el push, apply pdf vuelve a renderizar la versión antigua del servidor e ignora los cambios locales.

PDF y ajuste a una página

apply pdf usa el binario local de typst. Sin él, el comando sale con éxito con un enlace al panel y una sugerencia de instalación. apply shrink comprueba el conteo de páginas cuando hay un renderizador disponible, se detiene sin gastar si el currículum ya cabe y guarda el YAML revisado de vuelta en el kit.

Qué cuesta dinero

  • Gratis: inicio de sesión, gestión de cuentas y claves, comandos de currículum, consultas del plan y lecturas del seguimiento.
  • Hunter Pass más créditos: apply create y apply shrink. Una comprobación previa rechaza los planes gratuitos o los saldos insuficientes antes de la generación.
  • Hunter Pass: crear entradas de seguimiento, incluidas las derivadas de un kit de postulación. El estado, las notas, la eliminación y las lecturas no están restringidos.
  • Los fallos de generación los reembolsa el backend. La CLI nunca modifica los saldos por sí misma.

Guías de principio a fin

Flujo por lotes

Sube un currículum fuente, inicia un kit por cada descripción de empleo guardada sin esperar, sondea cada ID, renderiza los PDFs y registra las postulaciones que realmente se enviaron.

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

Postulación guiada por el agente

Para trabajar de una en una, deja que el agente cree e inspeccione el kit, copie la carta de presentación y mueva el registro de seguimiento por el flujo de estados real de la postulación.

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 salida JSON

Los ejemplos de abajo muestran las estructuras críticas para la orquestación. Los campos anulables permanecen presentes. En modo watch, los objetos de progreso se emiten uno por línea antes del 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 } }

Los comandos de listado envuelven las filas en los arrays cvs, kits, applications o keys. Los comandos de detalle devuelven el registro completo, incluidos los metadatos de empleo anulables, las marcas de tiempo, los IDs de archivos vinculados, el contenido fuente y la URL del panel.

Códigos de salida y catálogo de errores

Todos los comandos salen con 0 en caso de éxito y con 1 en caso de error. En modo JSON, inspecciona error.code. Los códigos de error del backend de la generación y del ajuste se pasan sin cambios. PAID_PLAN_REQUIRED en una cuenta gratuita es un comportamiento esperado, no una avería: los kits de postulación y las nuevas entradas de seguimiento requieren un Hunter Pass activo, y suscribirse lo resuelve.

  • Autenticación y perfiles: 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ículums y kits de postulación: 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.
  • Seguimiento: BAD_STATUS, BAD_OUTCOME, OUTCOME_REQUIRES_CLOSED, APP_EMPTY, APP_ARG_CONFLICT, PAID_PLAN_REQUIRED, KIT_NOT_READY, NOT_FOUND.