Cavuno CLI

Manage Cavuno from the terminal — pipeable commands and exit codes

Install

The CLI is published on npm as cavuno. Install it globally, or run it once with npx.

bash

123
npm install -g cavuno
# or
npx cavuno --help

Authentication

Set two environment variables. Mint a key in the Cavuno dashboard under Settings → API keys. The plaintext secret is shown once at creation — copy it to your secrets manager immediately.

bash

1234
export CAVUNO_API_KEY='cavuno_live_xxxxxxxxxxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
export CAVUNO_API_URL='https://api.cavuno.com/v1'

cavuno usage get

The CLI fails fast at startup if CAVUNO_API_KEY is missing or doesn’t match the cavuno_live_* format — you don’t wait on a 401 round-trip to see the error.

Global flags

Flag	Purpose
`--api-url <url>`	Override `CAVUNO_API_URL` for this invocation
`--format <json\|table>`	Output format. Default `json` (pipe-friendly)
`--help`	Print help for the command or subcommand
`--version`	Print the CLI version

Output formats

The default json output is the API response body verbatim — pipe it into jq for scripts. The optional table format pretty-prints key fields for terminal viewing.

bash

1
cavuno jobs list --status published --format table

Exit codes

The CLI exits with a stable code per error class. Scripts can branch on these without parsing stderr.

Code	Reason
`0`	Success
`1`	Authentication failure — missing or malformed CAVUNO_API_KEY, 401 auth_unauthenticated
`2`	Validation error — 400 validation_bad_request, missing required CLI flag
`3`	Authorization failure — 403 auth_forbidden
`4`	Resource not found — 404 *_not_found
`5`	Plan / quota — 409 jobs_quota_exceeded, 403 jobs_plan_cannot_publish
`6`	Rate limited — 429 rate_limited (Retry-After printed)
`7`	State conflict — 409 jobs_already_published, jobs_not_published, jobs_already_archived
`10`	Unknown server error — 500 or unmapped
`11`	Network error — DNS failure, connection refused, timeout

Failure messages on stderr include the API code, message, validation issues (when present), Retry-After (on 429), and X-Request-Id (when present). Echo the request ID when filing support tickets.

jobs

Manage jobs in the authenticated account.

`cavuno jobs list`

List jobs (paginated).

Maps to GET /v1/jobs (POST /v1/jobs/search when --search is set)

Synopsis

bash

1
cavuno jobs list [options]

Options

Flag	Required	Description
`--status <status>`	no	Filter by status (draft\|published\|expired\|archived)
`--company-id <id>`	no	Filter by company ID
`--search <query>`	no	Free-text search; routes through POST /v1/jobs/search
`--limit <n>`	no	Page size 1-100 (default 50)
`--cursor <cursor>`	no	Pagination cursor from previous response

Examples

bash

12
# All jobs (first page)
cavuno jobs list

bash

12
# Published only
cavuno jobs list --status published --limit 100

bash

12
# Published jobs at a single company
cavuno jobs list --status published --company-id k17abc...

`cavuno jobs get`

Fetch a single job by ID (enriched with description, company, places).

Maps to GET /v1/jobs/:id

Synopsis

bash

1
cavuno jobs get <id>

Arguments

Name	Required	Description
`id`	yes	Job ID

Examples

bash

1
cavuno jobs get k17abc...

bash

1
cavuno jobs get k17abc... | jq -r .title

`cavuno jobs create`

Create a draft job.

Maps to POST /v1/jobs

Synopsis

bash

1
cavuno jobs create [options]

Options

Flag	Required	Description
`--title <title>`	yes	Job title (required)
`--description <text>`	no	Description (markdown/HTML)
`--slug <slug>`	no	URL slug; auto-derived from title if omitted
`--company-id <id>`	no	Company ID (must belong to your account)
`--application-url <url>`	no	Application URL or `mailto:`/email
`--employment-type <type>`	no	full_time\|part_time\|contract\|internship\|temporary\|volunteer\|other
`--remote-option <opt>`	no	on_site\|hybrid\|remote
`--seniority <level>`	no	entry_level\|associate\|mid_level\|senior\|lead\|principal\|director\|executive
`--remote-sponsorship <opt>`	no	yes\|no\|unknown — visa sponsorship for remote candidates
`--remote-permits <json>`	no	JSON array, e.g. '[{"type":"country","value":"US"}]' — work-permit scope
`--remote-timezones <json>`	no	JSON array, e.g. '[{"type":"all","value":"all"}]' — timezone constraint (auto-derived from --remote-permits when omitted)
`--office-locations <json>`	no	JSON array, e.g. '[{"city":"Berlin","country":"DE"}]' — required for on_site/hybrid
`--in-office-period <opt>`	no	per_week\|per_month\|per_year — denominator for --in-office-frequency (hybrid)
`--in-office-frequency <n>`	no	In-office count per period (hybrid)
`--salary-min <n>`	no	Minimum salary
`--salary-max <n>`	no	Maximum salary
`--salary-currency <code>`	no	ISO 4217 currency (e.g. USD, EUR, GBP)
`--salary-timeframe <opt>`	no	per_year\|per_month\|per_week\|per_day\|per_hour
`--education-requirements <list>`	no	Comma-separated values: high_school,associate_degree,bachelor_degree,professional_certificate,postgraduate_degree,no_requirements
`--experience-months <n>`	no	Minimum experience required, in months
`--experience-in-place-of-education`	no	Allow equivalent experience to substitute for education
`--is-featured`	no	Mark as a featured job on the public board
`--expires-at <iso>`	no	Expiry as ISO 8601 datetime (parsed to epoch ms)

Examples

bash

12
# Minimal
cavuno jobs create --title "Senior Backend Engineer"

bash

12345678
# Common remote-only case
cavuno jobs create \
  --title "Senior Platform Engineer" \
  --description "We’re hiring..." \
  --employment-type full_time \
  --remote-option remote \
  --seniority senior \
  --company-id k18acme...

bash

1234567
# Hybrid role (requires --office-locations)
cavuno jobs create \
  --title "Staff Engineer" \
  --remote-option hybrid \
  --in-office-period per_week \
  --in-office-frequency 2 \
  --office-locations '[{"city":"Berlin","country":"DE"}]'

bash

12
# Capture the new ID
NEW_ID=$(cavuno jobs create --title "Test" | jq -r .id)

`cavuno jobs update`

Update fields on an existing job.

Maps to PATCH /v1/jobs/:id

Synopsis

bash

1
cavuno jobs update <id> [options]

Arguments

Name	Required	Description
`id`	yes	Job ID

Options

Flag	Required	Description
`--title <title>`	no	1–200 chars
`--description <text>`	no	Description (markdown/HTML)
`--slug <slug>`	no
`--company-id <id>`	no	Company ID (must belong to your account)
`--application-url <url>`	no	Application URL or `mailto:`/email
`--employment-type <type>`	no
`--remote-option <opt>`	no	on_site\|hybrid\|remote
`--seniority <level>`	no
`--remote-sponsorship <opt>`	no	yes\|no\|unknown
`--remote-permits <json>`	no	JSON array; pass `[]` to clear
`--remote-timezones <json>`	no	JSON array; pass `[]` to clear (PATCH never auto-re-derives)
`--office-locations <json>`	no	JSON array; required when --remote-option is on_site/hybrid
`--in-office-period <opt>`	no	per_week\|per_month\|per_year
`--in-office-frequency <n>`	no	Hybrid in-office count per period
`--salary-min <n>`	no	Minimum salary
`--salary-max <n>`	no	Maximum salary
`--salary-currency <code>`	no	ISO 4217 currency (e.g. USD, EUR, GBP)
`--salary-timeframe <opt>`	no	per_year\|per_month\|per_week\|per_day\|per_hour
`--education-requirements <list>`	no	Comma-separated list
`--experience-months <n>`	no	Minimum experience required, in months
`--experience-in-place-of-education <bool>`	no	true\|false (string accepted; PATCH semantics — explicit value required)
`--is-featured <bool>`	no	true\|false (string accepted; PATCH semantics — explicit value required)
`--expires-at <iso>`	no	ISO 8601 datetime (parsed to epoch ms); pass `null` to clear

Examples

bash

12
# Rename
cavuno jobs update k17abc... --title "Renamed role"

bash

1234
# Re-author the remote-permit set + sponsorship
cavuno jobs update k17abc... \
  --remote-permits '[{"type":"country","value":"US"}]' \
  --remote-sponsorship yes

bash

12
# Clear an existing expiry
cavuno jobs update k17abc... --expires-at null

bash

12
# Mark as featured
cavuno jobs update k17abc... --is-featured true

`cavuno jobs publish`

Publish a job (draft or expired → published).

Maps to POST /v1/jobs/:id/publish

Synopsis

bash

1
cavuno jobs publish <id> [options]

Arguments

Name	Required	Description
`id`	yes	Job ID

Options

Flag	Required	Description
`--expires-at <iso>`	no	Optional ISO 8601 expiry timestamp

Examples

bash

1
cavuno jobs publish k17abc...

bash

1
cavuno jobs publish k17abc... --expires-at 2026-12-31T23:59:59Z

`cavuno jobs pause`

Pause a published job (transition to draft).

Maps to POST /v1/jobs/:id/pause

Synopsis

bash

1
cavuno jobs pause <id>

Arguments

Name	Required	Description
`id`	yes	Job ID

Examples

bash

1
cavuno jobs pause k17abc...

`cavuno jobs expire`

Expire a published job immediately (sets expiresAt = now).

Maps to POST /v1/jobs/:id/expire

Synopsis

bash

1
cavuno jobs expire <id>

Arguments

Name	Required	Description
`id`	yes	Job ID

Examples

bash

1
cavuno jobs expire k17abc...

`cavuno jobs duplicate`

Duplicate a job (creates a new draft copy).

Maps to POST /v1/jobs/:id/duplicate

Synopsis

bash

1
cavuno jobs duplicate <id>

Arguments

Name	Required	Description
`id`	yes	Job ID

Examples

bash

1
cavuno jobs duplicate k17abc...

bash

1
NEW_ID=$(cavuno jobs duplicate k17abc... | jq -r .id)

`cavuno jobs delete`

Hard-delete a job. Irreversible.

Maps to DELETE /v1/jobs/:id

Synopsis

bash

1
cavuno jobs delete <id>

Arguments

Name	Required	Description
`id`	yes	Job ID

Examples

bash

1
cavuno jobs delete k17abc...

usage

Inspect account-level usage and limits.

`cavuno usage get`

Show the account's active-jobs usage and plan limit.

Maps to GET /v1/usage

Synopsis

bash

1
cavuno usage get

Examples

bash

1
cavuno usage get

companies

Manage companies in the authenticated account.

`cavuno companies list`

List companies (paginated).

Maps to GET /v1/companies

Synopsis

bash

1
cavuno companies list [options]

Options

Flag	Required	Description
`--search <query>`	no	Substring search on name
`--limit <n>`	no	Page size 1-100 (default 50)
`--cursor <cursor>`	no	Pagination cursor

Examples

bash

1
cavuno companies list

bash

1
cavuno companies list --search acme --limit 10

`cavuno companies get`

Fetch a single company by ID.

Maps to GET /v1/companies/:id

Synopsis

bash

1
cavuno companies get <id>

Arguments

Name	Required	Description
`id`	yes	Company ID

Examples

bash

1
cavuno companies get k18acme...

`cavuno companies create`

Create a company.

Maps to POST /v1/companies

Synopsis

bash

1
cavuno companies create [options]

Options

Flag	Required	Description
`--name <name>`	yes	Company name (required)
`--slug <slug>`	no	URL slug; auto-derived from --name if omitted
`--website <url>`	no	Website URL
`--summary <text>`	no	Short summary (≤280 chars)
`--description <text>`	no	Long-form description (≤25,000 chars)
`--x-url <handle-or-url>`	no	X (Twitter) handle or profile URL
`--linkedin-url <url-or-path>`	no	LinkedIn company page URL or path
`--facebook-url <url-or-path>`	no	Facebook company page URL or path

Examples

bash

1
cavuno companies create --name "Acme Corp"

bash

1234
cavuno companies create \
  --name "Acme Corp" \
  --website https://acme.com \
  --summary "World-class widgets"

`cavuno companies update`

Update a company (partial).

Maps to PATCH /v1/companies/:id

Synopsis

bash

1
cavuno companies update <id> [options]

Arguments

Name	Required	Description
`id`	yes	Company ID

Options

Flag	Required	Description
`--name <name>`	no	New name
`--slug <slug>`	no	New URL slug
`--website <url>`	no	New website URL
`--summary <text>`	no	New summary
`--description <text>`	no	New long-form description
`--x-url <handle-or-url>`	no	New X handle or profile URL
`--linkedin-url <url-or-path>`	no	New LinkedIn URL or path
`--facebook-url <url-or-path>`	no	New Facebook URL or path

Examples

bash

1
cavuno companies update k18acme... --name "Acme, Inc."

bash

1
cavuno companies update k18acme... --website https://acme.io

`cavuno companies delete`

Delete a company and cascade-delete its jobs.

Maps to DELETE /v1/companies/:id

Synopsis

bash

1
cavuno companies delete <id>

Arguments

Name	Required	Description
`id`	yes	Company ID

Examples

bash

1
cavuno companies delete k18acme...

`cavuno companies upload-logo`

Upload or replace a company logo.

Maps to POST /v1/companies/:id/logo

Synopsis

bash

1
cavuno companies upload-logo <id> <file>

Arguments

Name	Required	Description
`id`	yes	Company ID
`file`	yes	Path to a PNG, JPEG, WebP, or GIF logo file

Examples

bash

1
cavuno companies upload-logo k18acme... ./acme-logo.png

`cavuno companies delete-logo`

Delete a company logo.

Maps to DELETE /v1/companies/:id/logo

Synopsis

bash

1
cavuno companies delete-logo <id>

Arguments

Name	Required	Description
`id`	yes	Company ID

Examples

bash

1
cavuno companies delete-logo k18acme...

`cavuno companies find-by-domain`

Resolve a company by website domain (uses search endpoint).

Maps to POST /v1/companies/search

Synopsis

bash

1
cavuno companies find-by-domain <domain>

Arguments

Name	Required	Description
`domain`	yes	Website domain (e.g. acme.com)

Examples

bash

1
cavuno companies find-by-domain acme.com

`cavuno companies find-or-create`

Resolve to an existing company by domain or create one.

Maps to POST /v1/companies/find-or-create

Synopsis

bash

1
cavuno companies find-or-create [options]

Options

Flag	Required	Description
`--name <name>`	yes	Company name
`--website <url>`	no	Website URL (used for dedup)

Examples

bash

1
cavuno companies find-or-create --name "Acme Corp" --website acme.com

`cavuno companies search`

Search companies by name.

Maps to POST /v1/companies/search

Synopsis

bash

1
cavuno companies search <query> [options]

Arguments

Name	Required	Description
`query`	yes	Free-text query

Options

Flag	Required	Description
`--limit <n>`	no	Page size 1-100 (default 25)

Examples

bash

1
cavuno companies search "acme" --limit 10

`cavuno companies list-jobs`

List jobs at a company (any status, optional filter).

Maps to GET /v1/companies/:id/jobs

Synopsis

bash

1
cavuno companies list-jobs <id> [options]

Arguments

Name	Required	Description
`id`	yes	Company ID

Options

Flag	Required	Description
`--status <status>`	no	Filter by status (draft\|published\|expired\|archived)
`--limit <n>`	no	Page size 1-100 (default 50)

Examples

bash

1
cavuno companies list-jobs k18acme... --status published

CLI version 0.2.0 · Generated 2026-05-05