CLI Reference

smartchats is the command-line interface for the SmartChats stack. One tool covers the whole lifecycle: install, configure, launch, observe, stop, upgrade, sign in to the cloud, and move data around.

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

Install

See Quick Start. The short version:

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

Top-level

smartchats <command> [options]

If you run smartchats with no arguments:

• No config and no source reachable → runs setup (guided first run).
• Otherwise → runs start on the last-used port.

If the first argument is a flag other than --help or --version, the CLI routes to the legacy launch command (for older npx smartchats --no-prompt scripts).

To check the installed version, run:

smartchats --version
# Output: 0.x.y

-v and -V work too. Use smartchats help <command> or smartchats <command> --help for per-command details.

Lifecycle

smartchats setup

Guided first run. Detects the install, checks the system, prompts for API keys, writes .env, and starts the stack.

smartchats setup [options]

What it walks through, in order:

1. Install: a binary install uses ~/.smartchats. Otherwise it locates a source checkout ($SMARTCHATS_HOME, a directory walk, config.smartchatsHome) or clones one to ~/.smartchats/cli/source ($XDG_DATA_HOME/smartchats/cli/source if that variable is set).
2. System check: free disk (warns below 3 GB). Source and npm installs also need bun and surreal, and setup stops with an install command if either is missing.
3. API keys: walks OpenAI, Anthropic, Google and Serper. For each, it shows what it found in your environment or .env and lets you keep or replace it.
4. Write + start: writes .env and runs start. The stack is up at http://localhost:3000 when the wizard exits.

smartchats env

Interactively configure provider API keys. Same prompt loop as the key step of setup, with no system check and no start. Use it to rotate keys or enable a provider later.

smartchats env [options]

It walks OpenAI, Anthropic, Google (Gemini) and Serper. For each one it shows what’s already set and lets you keep it, replace it, or remove it. It writes to ~/.smartchats/.env for a binary install (the same file you mount into Docker at /root/.smartchats/.env) or <repo>/.env for a source install.

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

smartchats restart           # bare-metal install
docker restart smartchats    # docker install

To check what’s configured without prompts, run:

smartchats env --list
# Output:
#   ✓ 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)      not set  (optional)

smartchats start

Launches the local stack as detached child processes. Re-running while the stack is up and healthy prints the URL and exits.

smartchats start [options]

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

start reads .env from the install root (or repo root) and your shell environment. A shell variable wins over the same name in .env.

When detached (the default), start returns 0 once both processes report ready. PIDs are written to ~/.smartchats/run/pids.json.

smartchats stop

Stops the running stack. Sends SIGTERM, waits, then sends SIGKILL.

smartchats stop [--timeout <ms>]

smartchats restart

stop, then start. All start flags are forwarded.

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]

To check the stack, run:

smartchats status
# Output:
#   surreal  pid ✓ 12345  port ✓ 8000   up 2m 14s
#   server   pid ✓ 12346  port ✓ 3000   up 2m 14s
#
# ✔ Stack healthy. Open: http://localhost:3000

--json prints { "up": ..., "procs": [...] }, or { "up": false, "reason": "no-pid-file" } when nothing is running.

smartchats logs

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

smartchats logs [options]

smartchats dev

Hot-reload development stack. Runs bin/devserve in the smartchats source, so it needs a source checkout.

smartchats dev [-- <devserve-args>]

Anything after -- goes to bin/devserve unchanged. It has two target modes:

Other devserve flags: --port=<n> (Next.js port, default 3000), --no-server, --no-app, --no-prebuild, --no-surreal, --clean. Run bin/devserve --help for details.

smartchats dev -- --target=aio --rebuild

See Contributing for the development workflow.

smartchats upgrade

Upgrades a binary install by re-running the installer in place. Your data directory, .env and config.json are kept.

smartchats upgrade [options]

It runs curl -fsSL https://smartchats.ai/install | bash -s -- --non-interactive --version <tag> --prefix <install-root>. Run smartchats restart afterwards to use the new binaries.

For an npm install it prints npm install -g smartchats-ai@latest and exits 1. For a source checkout it tells you to git pull and exits 1.

Devices

The computer running SmartChats needs no pairing. A phone or another computer shows Pair this device and asks for a code. See Security.

smartchats pair

Prints a 6-digit code for one device, valid 5 minutes.

smartchats pair [--json] [--port <n>]
# Pairing code: 482 913   (valid 5 min, one device)
 
docker exec smartchats smartchats pair    # Docker

--json prints {"code": "482913", "expires_at": 1760000000000}.

smartchats devices

smartchats devices [--json]          # id, name, paired, last used
smartchats devices revoke <id>       # the device must pair again

Cloud

smartchats login

Browser sign-in to the SmartChats cloud. Clears any cached token first, then caches the new credentials at ~/.smartchats-mcp/credentials.json, the same file the MCP server reads.

smartchats login

smartchats logout

Clears cached cloud credentials.

smartchats logout

smartchats whoami

Shows the signed-in cloud user (uid, email, project, credentials file). If no credentials are cached, it starts the browser sign-in.

smartchats whoami

smartchats data

Moves user data between deployments as a JSON bundle. Use it for backups, debugging, and moving between local and cloud.

smartchats data export <file> [options]
smartchats data import <file> [options]

Each flag also accepts a space instead of = (for example --target cloud).

Without --tables, export writes logs, metrics, user_entities, user_relations, user_data, app_data, sessions, cortex, cortex_dynamic_functions, smartchats_apps and smartchats_app_installs. Telemetry tables are never exported. The bundle file is written with 0600 permissions.

Import upserts every row by id, so it’s safe to re-run. Rows are written as the user of the target deployment.

smartchats data export ~/backup.json --target=cloud
smartchats data import ~/backup.json --target=local --dry-run
smartchats data import ~/backup.json --target=cloud --tables=logs,metrics

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: critical.
3. surreal installed: critical.
4. Free disk ≥ 3 GB: warning only.
5. Docker installed: informational.
6. Image smartchats-aio:latest present: informational.
7. Container smartchats running: informational.
8. http://localhost:<port> responds: critical when the smartchats container is running.
9. Response is SmartChats: sanity check (catches port collisions).
10. LLM provider keys: warning if no OpenAI, Anthropic or Google key is found.

Exits 0 if every critical check passes, 1 otherwise.

smartchats home

Prints where smartchats lives and how the CLI found it.

smartchats home [--path-only]

In a binary install it prints the install root and the server, surreal and SPA paths. --path-only prints just one path (the install root in a binary install, otherwise the source root), or exits 1 with no output if neither is found:

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

Source root resolution order: $SMARTCHATS_HOME → walking up from the current directory looking for Dockerfile.aio → config.smartchatsHome (written after an auto-clone).

smartchats help <command>

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

Legacy

smartchats launch

Hidden from --help but still callable. Builds and runs the Docker all-in-one image (smartchats-aio:latest) from the smartchats source, cloning it first if needed. Use smartchats start for new installs.

smartchats launch [options]

Flags: --no-prompt, --rebuild, -d, --detached, --port <n>, --data-dir <path>, --tag <tag>, --test, --repo-path <path>. Run smartchats launch --help for details.

Environment

Provider keys are read from your environment and the .env file. A shell variable wins over .env. For each provider, the first name set wins, in this order:

The CLI prompts for the OpenAI, Anthropic, Google and Serper keys. The server reads all of them. See Self-Hosting for server settings.

Files

See also

• Quick Start: install and 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.