Configuration & Authentication

CLI config file, environment variables, gateway connection, output formats, and signing in.

The CLI stores its settings in a small JSON file, reads a handful of environment overrides, and connects to a Sophon Gateway over HTTP. This page covers all three, plus how output formats and authentication work.

Config File

CLI settings live in:

~/.sophon/config/cli.json

The file is created the first time you run sophon config set (or sophon onboard). Missing or corrupt files fall back to built-in defaults, so it is safe to delete.

Key	Default	Description
`gatewayUrl`	`http://localhost:8080`	Base URL of the Gateway the CLI talks to.
`authToken`	(not set)	Bearer token for remote/self-hosted gateways. Personal tier needs none.
`defaultAgent`	`default`	Agent used when a command doesn't name one.
`defaultFormat`	`table`	Output format: `table`, `json`, or `csv`.
`theme`	`dark`	The interactive theme. `/theme`'s picker writes one of `indigo-core`, `deep-void`, `graphite` or `daylight` here, and the full-screen chat reads it; the other surfaces resolve from `SOPHON_THEME` and the terminal probe instead — see Themes.
`fullScreen`	(unset → on)	The full-screen chat (v3). On by default — set `false` to fall back to the pinned input zone.
`v2`	(unset → on)	The enhanced interactive experience. On by default — set `false` to fall back to the classic prompt.
`pinnedInput`	(unset → on)	Pin the input zone to the bottom of the chat. Set `false` to use the classic framed prompt even on capable terminals.
`terminalTitle`	(unset → on)	Set the terminal window/tab title while the chat runs.
`defaultThinking`	(unset → auto)	Extended-thinking level: `auto`, `off`, `fast`, or `full`. Written by the `/thinking` command in the chat.
`greeting`	(unset → on)	Show the per-day greeting in the header card (pinned and classic surfaces).
`tokensFooter`	(unset → on)	Show the tokens / status footer ribbon.

Since v2.0.0 the full-screen chat is the default surface, and each layer below it has its own opt-out — the environment variable always wins over the file. SOPHON_CLI_FULLSCREEN=0 / "fullScreen": false drops to the pinned input zone; SOPHON_CLI_PINNED=0 / "pinnedInput": false drops from there to the classic prompt; SOPHON_CLI_V2=0 / "v2": false turns off the enhanced surface entirely. Nothing was removed — see Interactive Chat for the full fallback chain.

`sophon config`

Manage cli.json without editing it by hand:

sophon config path             # print the config file path
sophon config list             # show all effective values
sophon config get <key>        # read one key
sophon config set <key> <val>  # set a key and save
sophon config reset            # delete the file (restore defaults)
sophon config validate         # check the config is well-formed

sophon config set gatewayUrl https://sophon.example.com
sophon config set defaultAgent research
sophon config set defaultFormat json

config validate flags an empty or non-absolute gatewayUrl and an unrecognized defaultFormat.

Global Options

These flags work on every command and override the config file for that run:

Option	Description
`--gateway-url`, `-g`	Gateway URL (default `http://localhost:8080`).
`--format`, `-f`	Output format: `table`, `json`, or `csv`.
`--json`	Shorthand for `--format json`.
`--no-color`	Disable colored output (also honors `NO_COLOR`).
`--verbose`, `-v`	Enable verbose output.
`--version`	Print the CLI version.

sophon agents list -g https://sophon.example.com --json

Environment Variables

Environment overrides win over cli.json and are the recommended way to configure the CLI in CI or headless environments:

Variable	Overrides	Description
`SOPHON_GATEWAY_URL`	`gatewayUrl`	Gateway base URL.
`SOPHON_AUTH_TOKEN`	`authToken`	Bearer token for remote gateways.
`SOPHON_FORMAT`	`defaultFormat`	Output format.
`SOPHON_THEME`	`theme`	Theme name: `indigo-core`, `deep-void`, `graphite`, or `daylight`. See Themes for the per-surface resolution order.
`SOPHON_CLI_FULLSCREEN`	`fullScreen`	`0` disables the full-screen chat and falls back to pinned input (on by default).
`SOPHON_CLI_PINNED`	`pinnedInput`	`0` disables the pinned input zone (on by default on capable terminals).
`SOPHON_CLI_V2`	`v2`	`0` disables the enhanced experience (on by default).
`SOPHON_CLI_ACCESSIBLE`	—	`1` forces the linear classic prompt, for screen readers and other assistive tools. A Windows screen reader is detected automatically.
`SOPHON_CLI_TERMINAL_TITLE`	`terminalTitle`	`0` stops the chat from setting the terminal title.
`NO_COLOR`	—	`NO_COLOR=1` (or any value) strips all color from output.
`SOPHON_DEBUG`	—	Enable debug diagnostics.

Connecting to a Gateway

Every command needs a reachable Gateway. By default the CLI targets a local instance at http://localhost:8080.

Local Gateway — start one with sophon start for a full self-hosted deployment, then run commands with no extra flags.

Remote / self-hosted Gateway — point the CLI at the remote URL and supply a token:

sophon config set gatewayUrl https://sophon.example.com
sophon config set authToken <token>

Or, for CI and headless runs, use environment variables instead of writing to disk:

export SOPHON_GATEWAY_URL=https://sophon.example.com
export SOPHON_AUTH_TOKEN=$SOPHON_TOKEN
sophon agents list --json

Run sophon doctor to confirm the gateway is reachable and your auth, providers, and config check out. If a crash ever leaves your terminal stranded in the alternate screen or in raw mode, sophon doctor --reset-terminal restores it. See Self-hosting Configuration for the server side.

Authentication

On the personal tier there is no login — the Gateway auto-authenticates you as admin. sophon login simply reports "Personal tier — no login required."

For multi-user gateways:

sophon login      # prompts for email + password
sophon register   # create a new account
sophon logout     # clear the saved token
sophon whoami     # show the current user

whoami reports the personal-tier auto-admin when not logged in, and otherwise prints your display name and email.

For CI or headless agents, skip the interactive login and pass a token via SOPHON_AUTH_TOKEN (with SOPHON_GATEWAY_URL). See Scripting & Automation.

Output Formats

The CLI renders results as a table by default. Switch with --format (or -f), or use --json as a shortcut:

sophon agents list                 # table (default)
sophon agents list --format csv    # CSV
sophon agents list --json          # JSON (same as --format json)

Set a persistent default with sophon config set defaultFormat json or SOPHON_FORMAT. JSON and CSV are the formats to reach for in Scripting & Automation.

Data Directory

All CLI and Gateway state lives under ~/.sophon:

~/.sophon/
└── config/
    ├── cli.json              # CLI settings (this page)
    ├── cli-history.jsonl     # REPL command history
    └── models.json           # LLM provider keys (encrypted)

The CLI shares this directory with the Gateway, so provider keys configured elsewhere are available here too. For the full server-side layout, see Self-hosting Configuration.

Configuration & Authentication

On this page