CLI Reference

smartchats is the command-line interface for the SmartChats stack. One tool covers the entire lifecycle: install, configure, launch, observe, stop, sync with the cloud, and move data around.

Cloud auth is shared with the MCP server — log in once via smartchats login and any MCP-aware tool reading ~/.smartchats-mcp/credentials.json is authenticated too.

Install

See Quick Start. The two-second version:

curl -fsSL https://smartchats.ai/install | bash

Top-level

smartchats <command> [options]

If you run smartchats with no arguments:

• No config + no source reachable → runs setup (guided first-run).
• Config exists → runs start.
• Any flag present → routes to launch (back-compat for npx smartchats --no-prompt scripted callers).

Use smartchats help <command> for per-command details, or <command> --help.

Lifecycle

smartchats setup

Guided first-run. Detects what’s installed, prompts for missing API keys, writes .env, and launches the stack.

smartchats setup [options]

What it walks through, in order:

1. Source — locates an existing smartchats checkout ($SMARTCHATS_HOME, dir walk, config.smartchatsHome) or auto-clones one to ~/.smartchats/cli/source.
2. System check — verifies the bun runtime, surreal binary, and free disk (≥ 3 GB). Prints install instructions for anything missing.
3. API keys — walks OpenAI / Anthropic / Google / Serper. For each, shows what it found in $env or .env and lets you confirm or override.
4. Bearer token (optional) — for non-localhost deploys, configures SMARTCHATS_API_KEY.
5. Persist + start — writes .env, invokes start. You’re at http://localhost:3000 when the wizard exits.

smartchats env

Interactively configure provider API keys. Same prompt loop as smartchats setup’s key step, scoped to just keys — no system check, no start. For when you’ve got a working install and want to rotate keys or enable a new provider (e.g. Serper for web search).

smartchats env [options]

Walks each provider (OpenAI, Anthropic, Google Gemini, Serper). For each one, shows what’s already in $env or .env and lets you keep it, replace it, or remove it. Writes to the install root’s .env (typically ~/.smartchats/.env — the same file Docker mounts at /root/.smartchats/.env).

If the stack is running, restart afterward to pick up the new values:

smartchats restart           # bare-metal install
docker restart <container>   # docker install

Quick “what’s configured” check without prompts:

smartchats env --list
#   ✓ OpenAI                   sk-V…vGiE  (env $OPENAI_API_KEY)
#   ✓ Anthropic (Claude)       sk-a…iQAA  (env $ANTHROPIC_API_KEY)
#   ✓ Google (Gemini)          AIza…Uvbg  (env $GEMINI_API_KEY)
#   ✓ Serper (web search)      983d…4abf  (env $SERPER_API_KEY)

smartchats start

Launches the local stack as detached child processes. Idempotent — re-running while the stack is up + healthy is a no-op.

smartchats start [options]

The stack is two processes: surreal and smartchats-server. The server hosts both the static SPA and the API at /local-api/* on the same port.

On detach (the default), start returns 0 once both processes have reported ready. PIDs are written to ~/.smartchats/run/pids.json.

smartchats stop

Stops the running stack. SIGTERM with a timeout, SIGKILL fallback. Idempotent.

smartchats stop [--timeout <ms>]

smartchats restart

stop then start. All start flags forward verbatim.

smartchats restart [start-options...]

smartchats status

Shows what’s running, on what ports, with what health. Exits 0 if the stack is up and serving; 1 otherwise.

smartchats status [--json]

Example output:

  surreal  pid ✓ 12345  port ✓ 8000   up 2m 14s
  server   pid ✓ 12346  port ✓ 3000   up 2m 14s

✔ Stack healthy. Open: http://localhost:3000

--json emits a machine-readable shape — useful in monitoring scripts.

smartchats logs

Tails per-process log files (~/.smartchats/logs/surreal.log, ~/.smartchats/logs/server.log).

smartchats logs [options]

smartchats dev

Hot-reload development stack. Delegates to bin/devserve in the smartchats source — Next.js dev with HMR, Express side-by-side, SurrealDB in Docker.

smartchats dev [-- <devserve-args>]

Use this when you’re modifying SmartChats itself, not just running it. See Contributing for the development workflow.

Cloud

smartchats login

Browser-OAuth flow to the SmartChats cloud. Caches the refresh token at ~/.smartchats-mcp/credentials.json — same file the MCP server reads.

smartchats login

smartchats logout

Clears cached cloud credentials.

smartchats logout

smartchats whoami

Shows the currently-authenticated cloud user. Exits 1 if not logged in.

smartchats whoami

smartchats data export

Exports user data (logs, KG triples, todos, voice settings) to a JSON bundle. Use for backups, debugging, migration between local + cloud.

smartchats data export <file> --target=<cloud|local>

smartchats data import

Inverse of export. Upserts every row by id, so it’s safe to re-run.

smartchats data import <file> --target=<cloud|local>

Meta

smartchats doctor

Environment health check. Diagnoses what’s installed, what’s running, and what’s reachable.

smartchats doctor [--port <n>] [--json]

Checks (in order):

1. SmartChats context — where is the source root?
2. bun installed — required for the native-binary path.
3. surreal installed — required.
4. Free disk ≥ 3 GB — for builds + SurrealDB.
5. Docker installed — informational (only needed if you’re using the legacy launch path or building the AIO image).
6. AIO image present — informational.
7. Container smartchats running — informational.
8. http://localhost:<port> responds — critical when a stack is supposed to be up.
9. Response is SmartChats — sanity check (catches port collisions).
10. LLM provider keys — soft warning if none found.

Exits 0 if every critical check passes, 1 otherwise. --json emits the full result set as JSON.

smartchats home

Prints the resolved smartchats source root and how the CLI found it.

smartchats home [--path-only]

--path-only prints just the path (or exits 1 with no output if no source is reachable) — useful for scripting:

cd "$(smartchats home --path-only)"

Resolution order: $SMARTCHATS_HOME → dir walk → config.smartchatsHome (auto-clone remembers).

smartchats help <command>

Per-command help. Same as <command> --help.

Legacy

smartchats launch

Hidden from --help but still callable. The Docker AIO path (builds + runs smartchats-aio:latest). Use smartchats start for new installs.

smartchats launch [options]

Kept for back-compat with scripted callers that depend on the pre-start interface.

Environment

Provider keys (any of these are read; first match wins per provider):

Files

See also

• Quick Start — install + first-run.
• Self-Hosting — long-form deployment guide.
• Contributing — modifying SmartChats itself.
• MCP — expose smartchats to Claude Desktop and other MCP-aware tools via the shared credential store.