Skip to main content
Coding agents such as Claude Code, Cursor or Codex, and CI jobs, work best with Nohead through the nohead CLI: its --json output and exit codes cost an agent less context than a list of tools.

​
Set up the CLI

Install the CLI, then sign in on your own machine:
nohead login opens the web app for you to approve a key for the project (an agent can run it too, and shows you the code to check). nohead link <project> in a checkout keeps an agent working there in that project: see Projects. In CI, or for an agent that should act with a key of its own, create a key in the web app instead, as in Work with agents, and set it as NOHEAD_API_KEY. In CI, pin the CLI’s version too. Don’t keep NOHEAD_API_KEY set where you’ve logged in: while it’s set, it wins over saved keys and a folder’s link.

​
Output agents can rely on

  • With --json, stdout carries exactly one JSON document: the API’s own representation of the result, or for schema commands the plan.
  • Errors go to stderr. With --json, they use the API’s error envelope, { "error": { "type", "message", "request_id", "details" } }, and the CLI adds a few types of its own, such as network_error and schema_differs. Quote the request_id when you ask for support.
  • Rate limits (429), network failures and 5xx responses are retried on their own, and every write carries an Idempotency-Key, so a retry never applies a change twice.
  • Exit codes tell API errors, usage errors and an unreachable API apart: Output and exit codes lists them.

​
Schema as code in CI

Keep your collections and fields in a nohead.schema.yaml file in your repository, and let CI apply it. nohead schema diff shows a pull request’s changes, nohead schema push --yes applies the file after merge, and a scheduled nohead schema diff --exit-code catches changes someone made in the web app instead. A push never deletes collections or fields, and changes that rewrite existing values (field migrations) need --allow-migrations. Schema as code covers the file and the workflow.

​
Change content safely

  • Say why. --note is kept with the revision, the merge or the schema change it makes, and shown in history next to the key’s name and the client it came through, such as the CLI. Through the API, send the Nohead-Change-Note header; in the SDKs, pass changeNote (TypeScript) or change_note (Python, Ruby).
  • Don’t overwrite newer edits. --if-revision refuses the change with 412 if someone changed the record since the revision the agent read. Read it again, and apply the change again.
  • Propose, don’t publish. A draft holds changes until a person reviews them and merges them in the editor (Publish changes, or Apply changes for an unpublished record), or with nohead drafts merge.
  • Sync without duplicates. Through the API, an SDK or the MCP server’s create_record, creating a record with upsert_on, the key of a unique field such as a slug, updates the record that already has that value instead of adding another, so a sync job can run again and again.
  • Undo. Every record change is a revision you can revert, --dry-run previews a revert, and deleted records, fields, collections and assets can be restored for 30 days.

​
A snippet for your AGENTS.md

Tell your coding agent how your project uses Nohead, in AGENTS.md, CLAUDE.md or your tool’s rules file: