getcodestaff-cli

Command-line client for getcodestaff.io, talking to /api/v1.

Install

npm install
npm run build
npm link          # optional: puts `codestaff` on your PATH

Node 18+.

Authenticate

The CLI uses personal access tokens, not email/password. Create one at /dashboard/tokens — it is shown once.

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

Tokens are stored via conf (on macOS: ~/Library/Preferences/getcodestaff-cli-nodejs/config.json). CODESTAFF_TOKEN in the environment overrides the stored value, which is the usual choice for CI.

Password login is deliberately not supported: the site is gaining 2FA, and a password flow would mean entering a one-time code on every automated run.

Commands

codestaff whoami

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

codestaff get 4

codestaff create job                                       # interactive wizard
codestaff create job --title "…" --description "…" --budget 2500

codestaff apply 4                                          # prompts for cover letter
codestaff apply 4 --cover-letter "…" --rate '$95/hr'

codestaff status                                           # your applications, or
                                                           # applicants to your jobs
codestaff logout

Scripting

--json prints the raw payload and suppresses all spinners and colour:

codestaff list jobs --json | jq '.[] | {id, title, budgetCents}'

In --json mode the interactive wizards are disabled — pass the flags instead, or the command exits with a validation error rather than hanging on a prompt.

Exit codes

| Code | Meaning | |------|---------| | 0 | success | | 1 | generic failure | | 2 | authentication or authorization (login, or wrong role) | | 3 | not found | | 4 | validation / conflict (e.g. already applied) | | 5 | network failure after 3 retries |

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 env do not mutate the saved config, so a one-off command against staging leaves your normal setup alone.

Notes

• logout removes the token from this machine only. To kill a token everywhere, revoke it at /dashboard/tokens.
• The contractor directory returns opaque publicIds, never names or emails. Contact details are shared only after a hire completes — the API enforces this, not the CLI.
• Retries use exponential backoff (300ms / 600ms / 1200ms) and apply only to connection failures, 429s, and 5xx on GET. A failed POST is never retried, so a job or application cannot be double-submitted.