CodeStaff CLI

Install

The package is getcodestaff-cli; the command it installs is codestaff.

npm install -g getcodestaff-cli

Check it worked:

codestaff --version
codestaff list jobs

Browsing jobs needs no account. Everything else needs a token.

Authenticate

The CLI uses personal access tokens, not your password. Create one on the API tokens page — it is shown once and stored only as a hash, so copy it when it appears.

codestaff login                     # prompts, input masked
codestaff login --token cs_pat_…    # non-interactive, for CI

Tokens are saved with conf. On macOS that is ~/Library/Preferences/getcodestaff-cli-nodejs/config.json. The CODESTAFF_TOKEN environment variable overrides the stored value, which is usually what you want in CI.

Password login is deliberately unsupported. Accounts use two-factor sign-in, and a password flow would mean entering a one-time code on every automated run. Tokens are minted from an already-verified session and can be revoked individually.

Commands

List

codestaff list jobs
codestaff list jobs --skill design --min-budget 500 --max-budget 5000 --limit 10
codestaff list contractors --min-rate 50 --max-rate 150

list contractors is available to employers. Contractors are identified by an opaque ID — names and contact details are shared after a hire completes.

Get

codestaff get 4

Create a job

Run it bare for a wizard, or pass flags to script it.

codestaff create job

codestaff create job \
  --title "Senior React Developer" \
  --description "Rebuild our checkout flow." \
  --budget 5000 \
  --category "Software" \
  --location remote

Apply

codestaff apply 4
codestaff apply 4 --cover-letter "Ten years on payments systems." --rate '$95/hr'

Status

Contractors see their applications. Employers see applicants to their own jobs.

codestaff status

Session

codestaff whoami
codestaff logout

logout removes the token from this machine only. To kill a token everywhere, revoke it on the tokens page.

Scripting

--json prints the raw payload with no spinners or colour, so it pipes cleanly.

codestaff list jobs --json | jq '.[] | {id, title, budgetCents}'
codestaff status --json | jq '[.[] | select(.status == "applied")] | length'

In --json mode the interactive wizards are disabled — pass the flags instead. A scripted command that is missing required input exits with an error rather than hanging on a prompt you cannot see.

Configuration

codestaff --base-url https://staging.example.com list jobs
codestaff --api-prefix /api/v2 list jobs

Precedence is flag → environment (BASE_URL, API_PREFIX, CODESTAFF_TOKEN) → stored config → default. Flags and environment variables do not modify the saved config, so a one-off command against another environment leaves your normal setup alone.

Exit codes

Distinct per failure kind, so scripts can branch without parsing text.

Retries use exponential backoff (300ms, 600ms, 1200ms) and apply only to connection failures, rate limits and server errors on reads. A failed write is never retried, so a job or application cannot be submitted twice.

REST API

The CLI is a client for /api/v1. The same endpoints are available to anything that can send an HTTP request.

curl https://getcodestaff.io/api/v1/jobs

curl -H "Authorization: Bearer cs_pat_…" \
     https://getcodestaff.io/api/v1/me

Successful responses are wrapped in { "data": … }; failures return { "error": { "code", "message" } } with a matching HTTP status.