OpenGauss gauss CLI Subcommands and Flags Reference

The gauss binary is the top-level entry point for OpenGauss. Running gauss with no arguments drops you into the interactive REPL (equivalent to gauss chat). All other functionality is exposed as named subcommands described on this page. For slash commands typed inside the running session, see the Slash Commands reference. For Lean workflow commands, see the Workflow Commands reference.

gauss / gauss chat

Starts the interactive OpenGauss REPL. Running gauss with no arguments is identical to gauss chat.

gauss                                           # start interactive session
gauss chat                                      # same thing, explicit
gauss chat -q "What is the Lean 4 syntax for a theorem?"   # single query, non-interactive
gauss chat --model anthropic/claude-sonnet-4    # override model for this session
gauss chat --resume my-session-title            # resume by title or ID
gauss chat --continue                           # resume the most recent session
gauss chat --continue "My Lean project"         # resume by name (unquoted words also work)
gauss chat --worktree                           # isolated git worktree for parallel agents
gauss chat --checkpoints                        # enable filesystem checkpoints (use /rollback)
gauss chat --yolo                               # skip all dangerous-command approval prompts

-m / --model

string

Model identifier to use for this session, e.g. anthropic/claude-sonnet-4 or openai/gpt-4o. Overrides the default set by gauss model.

--provider

string

Inference provider to use. One of auto, openrouter, nous, openai-codex, anthropic, zai, kimi-coding, minimax, minimax-cn. Defaults to auto.

-t / --toolsets

string

Comma-separated list of toolsets to enable for this session.

-q / --query

string

Send a single query and exit (non-interactive mode). Useful for scripting.

-r / --resume

string

Resume a previous session by its ID or title. Run gauss sessions list to see available sessions.

-c / --continue

string

Resume a session by name, or the most recent CLI session when no argument is provided. Multi-word names do not need to be quoted on the command line (e.g. gauss -c Pokemon Agent Dev).

-v / --verbose

boolean

Enable verbose output, including detailed tool call previews.

-Q / --quiet

boolean

Quiet mode for programmatic or scripted use: suppresses the banner, spinner, and tool previews. Only the final response and session info are printed.

-w / --worktree

boolean

Run in an isolated git worktree, which allows multiple parallel agents to work on the same repository without conflicting.

--checkpoints

boolean

Enable filesystem checkpoints before destructive file operations. Use /rollback inside the session to restore a previous checkpoint.

--yolo

boolean

Bypass all dangerous-command approval prompts. Use with caution.

Use --quiet / -Q when calling gauss from scripts or CI pipelines. It strips all interactive decoration and outputs only the assistant’s final response, making the output easy to capture and parse.

gauss setup

Runs the interactive setup wizard that walks you through configuring inference providers, API keys, terminal preferences, gateway integrations, tools, and agent defaults. You can also run a single section by name.

gauss setup                    # full wizard
gauss setup model              # just the model/provider section
gauss setup terminal           # terminal appearance settings
gauss setup gateway            # messaging platform configuration
gauss setup tools              # tool enable/disable
gauss setup agent              # agent behaviour defaults
gauss setup --non-interactive  # use defaults and environment variables
gauss setup --reset            # reset configuration to factory defaults

section

string

One of model, terminal, gateway, tools, or agent. When omitted the full wizard runs.

--non-interactive

boolean

Skip all prompts and apply defaults or values from environment variables.

--reset

boolean

Reset configuration to defaults before running the wizard.

gauss doctor

Checks local prerequisites and configuration health, then prints a report. Doctor checks include:

Configured inference providers and API key validity
claude / codex CLI availability and authentication
uv / uvx availability (required for managed Lean workflows)
lake / lean availability
ripgrep (rg) availability
Active Gauss project detection in the current working directory
Managed-workflow backend and auth mode settings
Gateway and cron status

gauss doctor

Run gauss doctor whenever a workflow command fails unexpectedly. It reports the exact missing prerequisite and tells you how to fix it.

gauss config

Views and edits the Gauss configuration file (~/.gauss/config.yaml) and the .env file (~/.gauss/.env). Use this for direct configuration management outside of the interactive gauss setup wizard.

gauss config show          # print the current effective configuration
gauss config edit          # open config.yaml in $EDITOR
gauss config set model anthropic/claude-sonnet-4   # set a key directly
gauss config set terminal.backend claude-code       # set a nested key
gauss config path          # print the path to config.yaml
gauss config env-path      # print the path to .env
gauss config check         # check for missing or outdated config fields
gauss config migrate       # update config.yaml with any new options added since install

show

subcommand

Print the full current configuration as YAML.

edit

subcommand

Open ~/.gauss/config.yaml in $EDITOR (or $VISUAL).

set <key> <value>

subcommand

Set a configuration key to a value. Supports dotted paths for nested keys (e.g. terminal.backend).

path

subcommand

Print the absolute path to the active config.yaml file and exit.

env-path

subcommand

Print the absolute path to the active .env file and exit.

check

subcommand

Scan the current configuration for missing required fields or fields that have been superseded by newer schema versions.

migrate

subcommand

Non-destructively update config.yaml to add any new configuration fields introduced since your installation.

gauss version

Prints version information including the Gauss version, release date, Python version, OpenAI SDK version, and whether a newer version is available.

gauss version
gauss --version    # short flag, same output
gauss -V

gauss update

Pulls the latest commits from the upstream math-inc/OpenGauss repository and reinstalls Python dependencies. On Windows, if git file I/O fails (common with certain antivirus or NTFS filter drivers), it automatically falls back to downloading a ZIP archive of the main branch instead. After pulling new code, gauss update also:

Updates the managed Lean workflow runtime assets
Updates Node.js dependencies if package-lock.json is present
Checks for new required configuration fields and offers to configure them interactively
Auto-restarts the gateway service if it was running

gauss update

gauss model

Opens an interactive provider-and-model picker. It first prompts you to choose a provider (the active provider is shown at the top with a ← currently active marker), and then shows a searchable list of available models for that provider. Supported providers: OpenRouter, Nous Portal, OpenAI Codex, Anthropic (API key or Claude Pro/Max OAuth), Z.AI / GLM, Kimi / Moonshot, MiniMax, MiniMax China, and custom OpenAI-compatible endpoints.

gauss model

Custom endpoints you configure are saved to custom_providers in ~/.gauss/config.yaml so they reappear in the picker on the next run.

gauss tools

Opens a curses-based TUI for enabling and disabling individual tools per platform (CLI, Telegram, Discord, etc.). Pass --summary to print the current state without entering the interactive UI.

gauss tools             # interactive TUI
gauss tools --summary   # print enabled-tool summary and exit

--summary

boolean

Print a summary of enabled tools per platform and exit immediately.

gauss skills

Browses, installs, manages, and publishes skills from the skills registry (skills.sh), GitHub, ClawHub, and other well-known agent skill endpoints.

gauss skills browse                         # paginated browse of all skills
gauss skills browse --source official       # filter by source
gauss skills search "lean theorem proving"  # search registries
gauss skills install openai/skills/lean4    # install a skill by identifier
gauss skills inspect openai/skills/lean4    # preview without installing
gauss skills list                           # list installed skills
gauss skills check                          # check for updates to all installed skills
gauss skills update                         # update all outdated skills
gauss skills update lean4                   # update a single skill by name
gauss skills audit                          # re-scan all installed skills
gauss skills uninstall lean4                # remove an installed skill
gauss skills config                         # interactive enable/disable per skill
gauss skills publish ./my-skill --to github # publish to a registry
gauss skills snapshot export skills.json    # export installed skill set
gauss skills snapshot import skills.json    # import and install from a snapshot
gauss skills tap list                       # list configured skill sources
gauss skills tap add owner/repo             # add a GitHub repo as a skill source
gauss skills tap remove owner/repo          # remove a tap

Find a skill

gauss skills search <query> or gauss skills browse to discover available skills.

Preview it

gauss skills inspect <identifier> shows the skill manifest without installing anything.

Install

gauss skills install <identifier> clones and registers the skill.

Enable in a session

Use /skills inside the REPL or pass --skills <name> to gauss chat.

gauss sessions

Manages the SQLite session history store. All sessions from every platform (CLI, Telegram, Discord, WhatsApp) are stored here and accessible via subcommands.

gauss sessions list                          # list the 20 most recent sessions
gauss sessions list --source cli --limit 50  # filter by platform, custom limit
gauss sessions browse                        # interactive curses session picker
gauss sessions browse --source cli           # filtered interactive picker
gauss sessions export sessions.jsonl         # export all sessions to JSONL
gauss sessions export out.jsonl --source cli # export only CLI sessions
gauss sessions export out.jsonl --session-id abc123  # export a single session
gauss sessions delete abc123                 # delete a session (prompts for confirmation)
gauss sessions delete abc123 --yes           # skip confirmation
gauss sessions prune                         # delete sessions older than 90 days
gauss sessions prune --older-than 30         # custom age threshold
gauss sessions prune --older-than 30 --source telegram --yes  # no prompt
gauss sessions rename abc123 My New Title    # set or change a session title
gauss sessions stats                         # show total sessions, messages, DB size

list --source

string

Filter sessions by platform. Values include cli, telegram, discord, whatsapp, slack.

list --limit

integer

Maximum number of sessions to return. Defaults to 20.

export --session-id

string

Export a single specific session instead of all sessions.

delete --yes / -y

boolean

Skip the confirmation prompt when deleting a session.

prune --older-than

integer

Delete sessions older than N days. Defaults to 90.

browse --limit

integer

Maximum sessions to load into the interactive picker. Defaults to 50.

The browse subcommand opens a full-screen curses browser with live search filtering. Type any characters to filter by title, preview, session ID, or source. Press Enter to resume the selected session, Esc to clear the search or exit, and q to quit without selecting.

gauss gateway

Manages the OpenGauss messaging gateway, which enables Telegram, Discord, and WhatsApp integrations. The gateway can be run in the foreground, installed as a systemd user service, or targeted at a system-level service.

gauss gateway run              # run gateway in foreground
gauss gateway start            # start the gateway service
gauss gateway stop             # stop the gateway service
gauss gateway restart          # restart the gateway service
gauss gateway status           # show gateway status
gauss gateway status --deep    # deep health check
gauss gateway install          # install as a systemd user service
gauss gateway install --system # install as a system-level service (starts at boot)
gauss gateway install --force  # force reinstall
gauss gateway uninstall        # uninstall the service
gauss gateway setup            # configure messaging platform tokens
gauss gateway logs             # tail gateway logs

install --system

boolean

Install as a Linux system-level service that starts at boot, rather than a user-level service.

install --run-as-user

string

Specify the user account the system-level service should run as (system install only).

run --replace

boolean

Replace any existing gateway instance, useful when managed by systemd.

gauss insights

Analyzes session history to generate a report covering token usage, estimated costs, tool usage patterns, and activity trends.

gauss insights                     # last 30 days, all platforms
gauss insights --days 7            # last 7 days
gauss insights --source telegram   # filter to a single platform

--days

integer

Number of days of history to include in the analysis. Defaults to 30.

--source

string

Filter analytics to a single platform (e.g. cli, telegram, discord).

gauss uninstall

Removes OpenGauss from your system. By default it keeps ~/.gauss/ (configuration, session history, and managed assets) so that a reinstall can pick up where you left off. Pass --full to wipe everything.

gauss uninstall          # remove OpenGauss, keep ~/.gauss/
gauss uninstall --full   # remove everything including configs and session data
gauss uninstall --yes    # skip confirmation prompts

--full

boolean

Remove everything including ~/.gauss/ (configuration, session history, managed Lean assets).

--yes / -y

boolean

Skip confirmation prompts.

Runs the OAuth device-authorization flow for an inference provider. You are prompted to open a browser URL and confirm a code; on success, credentials are saved to ~/.gauss/auth.json.

gauss login                          # authenticate with the default provider (nous)
gauss login --provider nous          # explicitly target Nous Portal
gauss login --provider openai-codex  # authenticate with OpenAI Codex
gauss login --no-browser             # print the URL instead of opening a browser

--provider

string

Provider to authenticate with. One of nous or openai-codex. Defaults to nous.

--no-browser

boolean

Print the device-authorization URL instead of opening it automatically in the default browser.

gauss logout

Clears stored authentication credentials for a provider. Useful when rotating API keys or switching accounts.

gauss logout                      # clear credentials for the active provider
gauss logout --provider nous      # clear Nous Portal OAuth credentials
gauss logout --provider openai-codex  # clear Codex credentials

--provider

string

Provider to log out from. One of nous or openai-codex. Defaults to the active provider.

gauss status

Shows a summary of all OpenGauss component states: inference providers, gateway, managed workflow backend, active project, and authentication.

gauss status

CLI Reference

Toolsets & Skills

API & Embedding

OpenGauss gauss CLI Subcommands and Flags Reference

gauss / gauss chat

gauss setup

gauss doctor

gauss config

gauss version

gauss update

gauss model

gauss tools

gauss skills

gauss sessions

gauss gateway

gauss insights

gauss uninstall

gauss logout

gauss status

Build docs developers (and LLMs) love

CLI Reference

Toolsets & Skills

API & Embedding

Documentation Index

​gauss / gauss chat

​gauss setup

​gauss doctor

​gauss config

​gauss version

​gauss update

​gauss model

​gauss tools

​gauss skills

​gauss sessions

​gauss gateway

​gauss insights

​gauss uninstall

​gauss login

​gauss logout

​gauss status

Build docs developers (and LLMs) love

gauss / gauss chat

gauss setup

gauss doctor

gauss config

gauss version

gauss update

gauss model

gauss tools

gauss skills

gauss sessions

gauss gateway

gauss insights

gauss uninstall

gauss login

gauss logout

gauss status