CLI

The CLI is a Node.js REPL for talking to your motebit — streaming responses, tool approvals, slash commands, and a daemon mode for scheduled goals.

Running the CLI

Install it from npm and run it:

npm install -g motebit
motebit

Or run it once without a global install:

npx motebit

The default provider is Anthropic and needs ANTHROPIC_API_KEY. With no API key, run against a local model server (Ollama, LM Studio, llama.cpp, vLLM, or any OpenAI-compatible endpoint):

motebit --provider local-server

Or with options:

motebit \
  --provider anthropic \
  --model claude-sonnet-5-5 \
  --operator

Contributors: from a monorepo clone, pnpm --filter motebit start runs the same CLI from the package source instead of the published bundle; pass flags after -- (for example pnpm --filter motebit start -- --provider local-server).

CLI flags

Slash commands

Tool approval flow

When the agent requests a tool that requires approval, the CLI pauses and prompts:

Tool approval required: shellExec
  args: {"command": "ls -la"}
Allow? (y/n):

Type y to approve; anything else denies. The agent continues with the result (or denial) and completes the turn.

Identity bootstrap

The CLI uses the same identity system as the desktop app:

1. First launch generates an Ed25519 keypair
2. Private key is encrypted with PBKDF2 (AES-256-GCM) and stored in ~/.motebit/config.json
3. Identity and device are registered in the local SQLite database
4. Optional: register with a sync relay using --sync-url (or --sync) and --sync-token

Relay sync is opt-in

With no relay named, the CLI is fully local: it makes no network call to any relay — no device registration, no sync push, no heartbeat, no websocket — and motebit doctor reports info Sync off (opt in with --sync-url). Name a relay one of these ways:

motebit register with a relay named also persists it. Commands whose whole purpose is the relay (register, delegate, market, discover, rotate, machines, smoke x402, skills install/publish from the registry, verify-release, and the relay slash commands) refuse with a one-line message naming the opt-in when none is set — they never pick the public relay on their own. An existing sync_url in config.json keeps working unchanged.

Streaming output

By default, the CLI streams responses token-by-token. Tool calls appear inline:

> What files are in my home directory?
[calling readFile...]
[readFile done]
Your home directory contains the following files: ...

Use --no-stream to wait for the complete response before printing.

Subcommands

The CLI supports several subcommands beyond the default interactive REPL:

Serve flags

motebit serve exposes your motebit as an MCP server — other agents and tools can call it over stdio or HTTP.

# Stdio transport — for MCP host integration (Claude Desktop, etc.)
motebit serve

# HTTP transport — for remote agents
motebit serve --serve-transport http --serve-port 3100

# With identity governance
motebit serve --serve-transport http --identity ./motebit.md

# With external tools in direct mode (no LLM needed)
motebit serve --identity ./motebit.md --tools ./dist/tools.js \
  --serve-transport http --direct --self-test

In HTTP mode, the server registers with the sync relay (if configured) and sends a heartbeat every 5 minutes. Authentication is fail-closed: callers present a motebit signed token (Authorization: Bearer motebit:<signed-token>, e.g. the relay's per-task task:dispatch token) and everything else except /health gets 401. There is no static authToken setting in ~/.motebit/config.json.