Skip to content
NimbleBrain NimbleBrain NimbleBrain

nb (Interactive)

Running nb without a subcommand starts an interactive session with the NimbleBrain agent. The CLI auto-detects whether to use the terminal UI or headless pipe mode based on your terminal.

TUI mode

Section titled “TUI mode”

When you run nb in a terminal, it launches an Ink-based terminal UI with streaming responses, inline tool call display, and a line editor.

Terminal window
nb
[nimblebrain] Starting runtime...
[nimblebrain] 12 tools available
[nimblebrain] Ready.


> What can you do?


I can help you with tasks using the tools available from your installed apps.
Currently, you have access to bash commands through the @nimblebraininc/bash
bundle. I can also discover and install new apps from the mpak registry.


What would you like to work on?

Type your message and press Enter. The agent streams its response in real time. Press Ctrl+C to exit.

TUI features

Section titled “TUI features”
  • Streaming output — responses appear token by token as Claude generates them
  • Tool call display — you see each tool invocation and its result inline
  • Confirmation gate — the agent prompts you before running potentially destructive tools
  • Conversation persistence — conversations are saved to ~/.nimblebrain/conversations/ as JSONL files

Headless mode

Section titled “Headless mode”

When stdin is piped (not a TTY), nb switches to headless mode. It reads one message per line from stdin and writes the response to stdout. The conversation persists across lines until EOF.

Terminal window
echo "How many tools are available?" | nb
You currently have 12 tools available from the @nimblebraininc/bash bundle.

Multi-turn conversations

Section titled “Multi-turn conversations”

Each line of input is a separate message in the same conversation. The session stays alive until stdin closes (EOF):

Terminal window
printf "What bundles are installed?\nWhat tools does the first one provide?" | nb
You have one bundle installed: @nimblebraininc/bash.
The @nimblebraininc/bash bundle provides 3 tools: bash_exec, bash_read, and bash_write.

JSON output

Section titled “JSON output”

Use --json to get structured output. Each response is a single JSON object per line:

Terminal window
echo "What time is it?" | nb --json
{"response":"I don't have a clock tool, but I can run a bash command to check. Let me do that.\n\nThe current time is Wed Mar 25 14:00:00 HST 2026.","conversationId":"conv_a1b2c3","skillName":null,"toolCalls":[{"name":"bash_exec","input":{"command":"date"}}],"inputTokens":1247,"outputTokens":89,"stopReason":"end_turn"}

When an error occurs in JSON mode, you get an error object instead:

{"error":"Model rate limit exceeded"}

Flags

Section titled “Flags”
FlagDescription
--model <name>Override the default model for this session
--resume <id>Resume a previous conversation by ID
--jsonOutput structured JSON (headless mode only)
--config <path>Config file path
--workdir <dir>Working directory (default: ~/.nimblebrain)
--debugVerbose logging to stderr

Resuming conversations

Section titled “Resuming conversations”

Use --resume to continue a previous conversation. Pass the conversation ID from a prior session:

Terminal window
nb --resume conv_a1b2c3
[nimblebrain] Starting runtime...
[nimblebrain] Resuming conversation: conv_a1b2c3
[nimblebrain] Ready.


>

This works in both TUI and headless mode:

Terminal window
echo "What were we talking about?" | nb --resume conv_a1b2c3

Model override

Section titled “Model override”

Override the default model for a single session:

Terminal window
nb --model claude-sonnet-4-5-20250929

This takes precedence over the defaultModel value in your nimblebrain.json config.

Debug output

Section titled “Debug output”

Enable verbose logging to see runtime internals:

Terminal window
nb --debug

Debug output goes to stderr, so it does not interfere with headless stdout:

Terminal window
echo "Hello" | nb --debug 2>debug.log
Section titled “Related commands”