> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/ai/developers/cli-for-agents.md). # The CLI for agents Let your coding agent drive the Norbix CLI — sign in, write the agent's instructions, and when to choose the CLI or MCP. A coding agent (Claude Code, Codex, Cursor, …) already runs shell commands all day. Instead of loading hundreds of tools into its context, it can run `norbix …` like you do — and read one JSON answer per command. That is why Cloud marks the **Norbix CLI** as **Recommended** for coding agents in **Connect your AI**. MCP (Model Context Protocol, the standard way AI tools call outside services) stays the way for chat apps. ## How Norbix models it Three commands, run once by **you** in the project folder: ```sh npm i -g @norbix.ai/cli norbix login norbix ai init ``` | Step | What happens | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `npm i -g @norbix.ai/cli` | Installs the `norbix` command (Node.js 22 or newer). | | `norbix login` | Shows a one-time code such as `TKZK-CHRP` and opens Cloud's **/device** screen in your browser. You check the code, pick the roles (per project: Administrator, Developer, Data Editor, Viewer or your own role) and allow it. The CLI saves a session in `~/.norbix/session.json`. It acts as an **AI service user** named like *Norbix CLI (your computer, 56f448)* — never as you. | | `norbix ai init` | Writes short instructions for the agent into the folder (below). Nothing is sent to Norbix. | What `norbix ai init` writes (`--target`, default `claude`): | `--target` | Files | Read by | | ---------- | ----------------------------------------------------------- | ---------------------------------- | | `claude` | `.claude/skills/norbix/SKILL.md` and a block in `CLAUDE.md` | Claude Code | | `agents` | a block in `AGENTS.md` | Codex, OpenCode, Cursor and others | | `cursor` | `.cursor/rules/norbix.mdc` | Cursor | | `all` | all of the above | | `--dry-run` lists what it would write; an existing file is never overwritten without `--force`. The instructions tell the agent the CLI's contract: * run `norbix whoami --json` first; on exit code 4 (no credentials) stop and ask you — the agent never runs `norbix login` itself; * always `--json`: stdout is exactly one JSON document, a result or `{"error": {code, message, status, exit, fieldErrors, hint, docs}}`; * find commands with `norbix schema --json` (277 commands, each with `destructive` and `supportsDryRun`) and `norbix --help`; any endpoint without its own command through `norbix hub …` or `norbix api …`; * change in two steps: `--dry-run` prints the exact request and sends nothing, then the real call — with `--yes` when the command is destructive (without it the command exits 3 and sends nothing); * act on the exit code: 0 ok · 2 usage · 3 needs `--yes` · 4 auth · 5 not found · 6 validation · 7 network · 8 server · 9 cancelled. For CI and other runs without a person, skip `norbix login` and set `NORBIX_API_KEY` (an `nbsu_` key) and `NORBIX_PROJECT_ID` in the environment — see [Read-only keys](/codemash/ai/developers/read-only-keys.md#create-a-key-for-ci). {% hint style="warning" %} With `@norbix.ai/cli` 1.16.0 (the published version on 2026-10-07): * `norbix login` on the managed service stops with *Region is required when using the default norbix.ai endpoints* — add your region: `norbix login --region nb-eu-germany`. * A Hub that does not offer the browser sign-in yet makes the CLI fall back to user name and password (*Browser login is not available on this hub yet*). Use an API key instead: `norbix login --api-key nbsu_… --project pr_…`. * On a self-hosted installation `NORBIX_HUB_URL=… NORBIX_API_URL=… norbix login` works since 1.16.0 (1.15.1 ignored the two variables). More: [Norbix CLI → Sign in](/codemash/cli/cli.md#sign-in). {% endhint %} ## A run, end to end The agent checks who it is, reads, and prepares a change (an AI service user with the **Developer** role on one project, signed in through `norbix login`): ```sh norbix whoami ``` ``` Profile: default Auth: session (Norbix CLI (unknown computer, 56f448)) Project: pr_3dMEdKCg5DyxGuA4CtzS1F ``` ```sh norbix db find books --json ``` ```json { "list": { "items": [], "hasMore": false, "hasPrevious": false }, "responseStatus": { "isSuccess": true, "errors": [] } } ``` ```sh norbix ai service-user create --name "Report agent" --reach project --rights read --env TEST --dry-run ``` ``` Dry run — nothing was sent. Would call: hub.account.createAiServiceUser POST https://hub.norbix.ai/v2/account/ai/service-users ``` {% hint style="warning" %} One command of CLI 1.16.0 does not work against the current Hub: `norbix ai service-user create` sends the old `--reach` / `--rights` scope and is refused with `CM-ERRORS-AI-SU-016` (*Give the service user at least one role*) — create AI service users through `norbix login` or the Hub API for now. {% endhint %} ## CLI or MCP? | | Norbix CLI | MCP server | | ----------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Best for | Coding agents with a shell: Claude Code, Codex, Cursor | Chat apps without a shell: Claude Desktop, ChatGPT, Gemini | | Sign-in | `norbix login` (browser, roles) or an `nbsu_` key | OAuth in the browser (roles) or an `nbsu_` key | | Context cost | Small: the agent reads `--help` / `norbix schema` only when needed | Every listed tool's description sits in the context (418, or fewer with `?toolsets=`) | | Safety net | `--dry-run` on every change, `--yes` for destructive ones, exit codes | `requires_confirmation` handshake, `readOnlyHint` per tool | | Works in scripts and CI | yes, the same commands | needs an MCP client | | What it reaches | every SDK endpoint (`norbix hub` / `norbix api`) | the 418 endpoints marked as AI tools — [What agents can do](/codemash/ai/developers/what-agents-can-do.md) | You can use both: the CLI for the coding agent in your repo, MCP for the chat app on your desktop. Both act as AI service users with the roles you picked, and both show up in **Account → AI service users**. ## Where you use it * Install and sign-in details: [Norbix CLI](/codemash/cli/cli.md) * The MCP way: [MCP server](/codemash/ai/developers/mcp-server.md), [Connect your IDE](/codemash/ai/developers/connect-your-ide.md) * Safe roles for agents: [Read-only keys](/codemash/ai/developers/read-only-keys.md) * Cloud: avatar → **Connect your AI** ([Account](/codemash/cloud/account.md))