CLI

nib [options] [prompt]
nib <command> [options]

nib starts an interactive session in the current folder. With a prompt, the session starts with that message. With -p, it runs the prompt without the UI, prints the result and exits. The commands do one job each, such as signing in or adding an MCP server.

ExamplesCopy Anchor Link

nib                                      # interactive session in this folder
nib "explain the build pipeline"         # start with a prompt
nib -c                                   # continue the most recent session here
nib -r                                   # pick a session to resume
nib -w                                   # new session in its own git worktree
nib -m openai:gpt-6.1-sol --effort high  # choose model and effort
nib -p "list TODO comments in src/"      # headless: print the answer and exit
cat error.log | nib -p "what failed?"    # headless with piped input
nib -p "summarize the diff" --max-budget-usd 0.50 --output-format json

OptionsCopy Anchor Link

SessionCopy Anchor Link

• --continue, --resume and --from-pr can't be combined, and --fork-session requires --continue or --resume.
• --worktree and --session-id start a new session, so they can't be combined with resuming one.
• -r takes the next argument as the session to resume when it names one: an id (ses_…) or a handle (lowercase letters, marks and digits of any script, and dashes). A flag or a phrase after it stays what it was, and the picker opens.

Model and permissionsCopy Anchor Link

--allowedTools and --disallowedTools also accept the kebab-case spellings --allowed-tools and --disallowed-tools. Lists can be comma- or space-separated; Nib never splits inside parentheses, so "Bash(git log *),Edit" is two rules. Each system-prompt flag and its -file form are mutually exclusive.

The list flags (--allowedTools, --disallowedTools, --add-dir, --mcp-config) take every value up to the next flag, so a prompt typed after a list becomes part of it. Put the prompt first, as in nib -p "fix it" --allowedTools Read Edit, or end the list with --. The --allowedTools=<rule> form takes one value.

ConfigurationCopy Anchor Link

HeadlessCopy Anchor Link

• --output-format, --input-format, --max-budget-usd, --json-schema and --no-session-persistence require -p. --include-partial-messages requires --output-format stream-json.
• -p can't open the session picker, so --resume needs an explicit id in headless mode.
• --no-session-persistence deletes the session it ran in, so with --continue or --resume it needs --fork-session, and it can't be combined with --worktree.
• --bg doesn't wait for the run, so it can't be combined with stream-json input or output, --max-turns, --json-schema or --no-session-persistence.

DaemonCopy Anchor Link

With --daemon-url (or NIB_DAEMON_URL), the CLI connects to that daemon, with the token in NIB_DAEMON_TOKEN. Without a URL it uses the daemon running for the data directory, and when none is running it starts one for this run; --bg starts one that keeps running after nib exits.

In CI, that means a daemon starts for the run and stops when the run ends. To use your account there, register a device token with nib setup-token.

The daemon's token has no flag: a command line is visible to every user of the computer, and the token gives full control of your daemon.

OtherCopy Anchor Link

CommandsCopy Anchor Link

Every command takes --help.

nib acpCopy Anchor Link

Serves the Agent Client Protocol on stdio, so editors that speak it can run Nib; see JetBrains, Zed and ACP editors. It takes no prompt, because the editor sends prompts. Its options set the defaults for the sessions the editor creates and how to reach the daemon: -m/--model, --effort, --permission-mode, --dangerously-skip-permissions, --allow-dangerously-skip-permissions, the daemon options and --verbose. Each session's folder comes from the editor, so there's no --cwd.

nib importCopy Anchor Link

nib import <claude-code|codex|gemini|cursor> [options]
nib import --from <source> [options]

Converts another agent's configuration into .nib/, item by item: MCP servers, commands, skills, agents, rules, output styles, settings and permission rules. Secret values are never copied: they become ${VAR} references, and the variables to set are listed at the end. See Import your setup.

Every item is imported, with what it does shown beside it. From a project's own files, an item in one of these classes is left out, with the reason, unless you include its class with --include-risky:

What other items would run is checked where it runs: a project's hooks, environment variables and allow rules wait until you trust the folder, and every imported MCP server waits for your approval. User-level configuration (--user) imports as it is. A copied skill, command or agent is judged by what its frontmatter declares, never by its prompt.

nib import <file>Copy Anchor Link

nib import <file> [options]
nib import --paste <memories|instructions> [--source <service>] < text
nib import --runs
nib import --undo <id>

Brings your history from ChatGPT, Claude or Gemini into Nib, from the file their own export gave you: the zip, the folder it unpacks to, or conversations.json. Nib reads it on this computer and never signs in to those services. Conversations become read-only sessions, listed by their own dates and found by search. What an export leaves out (saved memories, a custom assistant's role) you can pipe in with --paste.

It asks before anything is written: whether to bring in the conversations, where each of the service's projects goes (a new project with its name, one you have open, or with the rest), where the conversations outside a project go ("Imported from ChatGPT" by default), and about every memory and instruction, shown in full. Those steer every future agent where they're put, so each starts at "Leave it out" and comes in only where you place it. A conversation that holds what looks like a secret, such as a key pasted into a chat, is flagged; it comes in as it is and stays on this computer. Images, audio and attached files aren't brought in yet.

The review needs a terminal. In a script, --dry-run shows what an export holds without writing anything.

nib exportCopy Anchor Link

nib export [path.zip]

Writes everything this computer holds in Nib to one zip, in open formats with a README that explains them: sessions (as JSON Lines and Markdown transcripts), instructions and memory, artifacts, projects, providers (named, never their keys) and settings. Nothing is uploaded to make it. Without a path it's nib-export-<date>.zip in the current folder. What the cloud holds (synced sessions, hosted artifacts, usage and billing) is its own download: Settings → Account → Your data in the app.

nib mcpCopy Anchor Link

add takes -t/--transport <stdio|http> (a URL implies http), -s/--scope <local|project|user> (local, the default, is you in this project; project is .mcp.json; user is everywhere), -e/--env KEY=value and -H/--header "Name: value" (both repeatable), --client-id <id> for a pre-registered OAuth client, and --callback-port <port> for a fixed OAuth callback. Put -- before a stdio server's command when its arguments start with -. Install guides that give an mcp add … command line work as nib mcp add …. See MCP servers.

nib pluginCopy Anchor Link

Plugins use the .claude-plugin/plugin.json format. They can run code on this computer, so an install or update that needs your consent says what the plugin can do and waits for --yes. Everything goes through the daemon's Hub, so the desktop app shows the same plugins. See Nib Hub.

nib teleportCopy Anchor Link

nib teleport [session] [options]
nib teleport --pull <teleport-id>

Continues a session on a new cloud computer: its code, the conversation and attached files (up to 25 MB) move there, and this copy is archived. A session that's working moves when its current turn ends. session is an id, handle or title; the default is the latest session in this folder.

nib login, nib logout, nib auth status, nib usageCopy Anchor Link

nib login signs you in through your browser; signing in with a link and a code sent to your email (--email) is coming soon. Without a browser (over SSH, on a server, or with --no-browser) it prints a link to open on any device, with a code to check. Then it links this computer to your account, as the desktop app does. nib logout undoes both. The sign-in is stored in the macOS Keychain, the Secret Service keyring on Linux or Windows Credential Manager, or in <data-dir>/cli/credentials.json (mode 0600) where there's none.

nib keysCopy Anchor Link

nib usage requestCopy Anchor Link

nib usage request [--credits <credits>] [--note <text>]
nib usage request --withdraw

Asks the owners of the organization you're signed in to for a higher monthly budget for Nib models, as Request more usage under Account → Usage does in the app. The owners decide. One request waits at a time: to change it, withdraw it and ask again. Owners set budgets themselves, so they don't ask, and a member with no budget has nothing to raise.

nib usage activityCopy Anchor Link

nib usage activity [--days <n>] [--json]
nib usage activity --csv [--days <n>]

For admins and owners: what the members of your organization did with Nib, as Activity under Account → Usage shows it in the app. It shows how many members were active against the plan's seats, the range's sessions, edits, lines and spend on Nib models and own keys, a row per member, and the five most used commands. Commands that a project or a person defined count together as "your own commands", because their names can name the work. The counts come from the members' computers, never code, prompts or file names, and only organizations on Team and Enterprise collect them. Days are whole UTC days, today included.

With --csv it writes a row per day and member instead, the file Export activity saves in the app: sessions, turns, edits, lines added and removed, and the spend on Nib models and on own keys.

nib usage exportCopy Anchor Link

nib usage export [--days <n>] > usage.csv

For admins and owners: your organization's spend as CSV on stdout, for chargeback. It's the file Export usage under Account → Usage saves in the app. Each row is one day, member and model, with the provider, the requests, the input and output tokens, the cost in US dollars, and whether Nib models or the member's own key served them.

nib org requestsCopy Anchor Link

nib org requests
nib org requests approve <id> [--credits <credits>]
nib org requests decline <id> [--note <text>] [--block]

For owners: what the members of your organization asked for, as Requests under Account → Organization shows it in the app. Requests waiting for an answer come first, then the last 30 days' answers, each with the id that approve and decline take. Approving sets the member's monthly budget for Nib models, in Nib credits, to what they asked for, or to --credits. A decline can carry a note, which the member reads in the email. A request that was already answered or withdrawn stays as it is.

nib setup-tokenCopy Anchor Link

Registers a Nib Cloud device for CI and stores its token. Create a key with the sync scope under Settings → API keys in Nib Cloud, then run nib setup-token and paste the key, or pipe it on stdin. The key is used once to register the device and isn't stored. By default the device token goes into the local daemon's cloud link (<data-dir>/cloud.json). With --print it's written once to stdout instead: save it as the CI secret NIB_DEVICE_TOKEN, next to NIB_CLOUD_URL.

Exit codesCopy Anchor Link

LanguageCopy Anchor Link

nib speaks English and Russian. Help, errors, questions and the interactive session follow the language in your user settings (a tag such as ru or a name such as Russian), else your terminal's locale (LC_ALL, LC_MESSAGES, LANG), else English. Output meant for programs stays in English: --output-format json and stream-json, the Agent SDK mode and --verbose logs.

Headless modeCopy Anchor Link

nib -p runs one prompt and exits. The prompt comes from the arguments, from stdin, or both: piped input is read when stdin isn't a terminal. With a prompt argument, piped input that hasn't started after 3 seconds is skipped, and nib says so on stderr; redirect stdin from /dev/null to skip the wait.

Nobody can answer prompts in headless mode, so:

• Permission requests are decided by your permission rules, --permission-mode, --allowedTools and --disallowedTools. Anything they don't allow is denied, and the agent is told how to proceed. Every denial is listed in permission_denials in the JSON result.
• Questions from the agent (AskUserQuestion) are answered with "No answer: running non-interactively. Use your best judgment and state the assumption."
• Forms from MCP servers (elicitation) are declined, and stderr names the server that asked.
• Budget limits that would pause a session stop the run instead.
• Workspace trust prompts don't appear.

# Allow tests and edits, nothing else
nib -p "make the failing test in auth.test.ts pass" \
  --allowedTools "Bash(bun test *)" Edit Write \
  --max-turns 25 \
  --output-format json

text outputCopy Anchor Link

The final assistant message, as plain text. Errors go to stderr.

json outputCopy Anchor Link

A single JSON object when the run ends. Field names follow the widely used headless result format (type, subtype, result, session_id, total_cost_usd, …), so existing scripts that parse it keep working.

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Fixed the token expiry check in src/auth/session.ts. All 48 tests pass.",
  "session_id": "ses_01JCQ8Z4X9T5V2M3N7K1P6R0WA",
  "num_turns": 7,
  "duration_ms": 41873,
  "total_cost_usd": 0.0871,
  "usage": {
    "input_tokens": 182340,
    "output_tokens": 2911,
    "reasoning_tokens": 1404,
    "cache_read_input_tokens": 151200,
    "cache_creation_input_tokens": 18420
  },
  "permission_denials": []
}

With --json-schema, the run must end with a structured answer. A turn that ends without one gets one reminder; if the next turn has none either, the run fails with error_max_structured_output_retries.

stream-json outputCopy Anchor Link

One JSON object per line while the run is in progress, then the same result object as json on the last line.

The first line describes the run:

{"type":"system","subtype":"init","session_id":"ses_01JC…","cwd":"/Users/me/code/app","model":"anthropic:claude-opus-5-5","permissionMode":"default","mcp_servers":[],"agents":[],"nib_version":"0.1.0","protocol_version":1,"daemon":"spawned"}

Each following line wraps one session event:

{"type":"event","session_id":"ses_01JC…","event":{"seq":12,"body":{"type":"tool.start", …}}}

Streaming deltas (assistant.delta, tool.progress) are included only with --include-partial-messages.

stream-json inputCopy Anchor Link

With --input-format stream-json, each line on stdin is a user message:

{"type":"user","message":{"role":"user","content":"Now add tests for it."}}

content can be a string or an array of content blocks ({"type":"text","text":"…"}, images and so on). This lets another program hold a multi-turn conversation with Nib over a pipe.

Interactive modeCopy Anchor Link

Slash commandsCopy Anchor Link

/init, /security-review, /simplify, /recap, /statusline and /loop come with Nib: the runner expands them, so they work the same in the desktop app, the CLI, VS Code and ACP clients. A skill or command of yours with the same name replaces the bundled one, and "disableBundledSkills": true in settings turns them off.

Skills you can invoke appear in the same / menu. A /name that's none of these, nor one of your skills, commands or an MCP server's prompts, isn't sent: the CLI says it's an unknown command and points to /help.

Prompt prefixesCopy Anchor Link

Keyboard shortcuts are listed in Keyboard shortcuts.

Environment variablesCopy Anchor Link