CLI

The OpenGPT0 CLI by default starts the TUI when run without any arguments.

opengpt0

But it also accepts commands as documented on this page. This allows you to interact with OpenGPT0 programmatically.

opengpt0 run "Explain how closures work in JavaScript"

---

tui

Start the OpenGPT0 terminal user interface.

opengpt0 [project]

Flags

Flag	Short	Description
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--fork		Fork the session when continuing (use with --continue or --session)
--prompt		Prompt to use
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--port		Port to listen on
--hostname		Hostname to listen on
--mdns		Enable mDNS discovery
--mdns-domain		Custom mDNS domain name
--cors		Additional browser origin(s) to allow CORS

---

Commands

The OpenGPT0 CLI also has the following commands.

---

agent

Manage agents for OpenGPT0.

opengpt0 agent [command]

---

create

Create a new agent with custom configuration.

opengpt0 agent create

This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.

Flags

Flag	Short	Description
--path		Directory to write the agent file to (defaults to global or .opengpt0/agent based on the prompt)
--description		What the agent should do
--mode		Agent mode: all, primary, or subagent
--permissions		Comma-separated list of permissions to allow (default: all). Available: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill. Anything omitted is denied. Alias: --tools
--model	-m	Model to use, in provider/model format

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.

---

list

List all available agents.

opengpt0 agent list

---

attach

Attach a terminal to an already running OpenGPT0 backend server started via serve or web commands.

opengpt0 attach [url]

This allows using the TUI with a remote OpenGPT0 backend. For example:

# Start the backend server for web/mobile access
opengpt0 web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
opengpt0 attach http://10.20.30.40:4096

Flags

Flag	Short	Description
--dir		Working directory to start TUI in
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--fork		Fork the session when continuing (use with --continue or --session)
--password	-p	Basic auth password (defaults to OPENGPT0_SERVER_PASSWORD)
--username	-u	Basic auth username (defaults to OPENGPT0_SERVER_USERNAME or opengpt0)

---

auth

Command to manage provider credential state. The default Browser provider does not store a model API key in OpenGPT0; sign in to ChatGPT in the dedicated Chromium profile instead. Ollama runs locally and normally uses the local OpenAI-compatible endpoint.

opengpt0 auth [command]

---

login

Use opengpt0 auth login only for legacy or advanced credential entries. Browser login happens in the ChatGPT Chromium profile, and Ollama does not need a real cloud API key.

opengpt0 auth login

When OpenGPT0 starts up it loads any stored credentials from ~/.local/share/opengpt0/auth.json, plus supported environment variables and project .env files.

Flags

Flag	Short	Description
--provider	-p	Provider ID or name to log in to
--method	-m	Login method label to use, skipping method selection

---

list

Lists provider credentials stored in the credentials file.

opengpt0 auth list

Or the short version.

opengpt0 auth ls

---

logout

Logs you out of a stored provider credential by clearing it from the credentials file.

opengpt0 auth logout

---

github

Manage the GitHub agent for repository automation.

opengpt0 github [command]

---

install

Install the GitHub agent in your repository.

opengpt0 github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.

---

run

Run the GitHub agent. This is typically used in GitHub Actions.

opengpt0 github run

Flags

Flag	Description
--event	GitHub mock event to run the agent for
--token	GitHub personal access token

---

mcp

Manage Model Context Protocol servers.

opengpt0 mcp [command]

---

add

Add an MCP server to your configuration.

opengpt0 mcp add

This command will guide you through adding either a local or remote MCP server.

---

list

List all configured MCP servers and their connection status.

opengpt0 mcp list

Or use the short version.

opengpt0 mcp ls

---

auth

Authenticate with an OAuth-enabled MCP server.

opengpt0 mcp auth [name]

If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

opengpt0 mcp auth list

Or use the short version.

opengpt0 mcp auth ls

---

logout

Remove OAuth credentials for an MCP server.

opengpt0 mcp logout [name]

---

debug

Debug OAuth connection issues for an MCP server.

opengpt0 mcp debug <name>

---

models

List available Browser and configured Ollama models.

opengpt0 models [provider]

This command displays models in the format provider/model.

This is useful for figuring out the exact Browser or Ollama model name to use in your config.

You can optionally pass a provider ID to filter models by that provider.

opengpt0 models browser

Flags

Flag	Description
--verbose	Use more verbose model output

---

run

Run opengpt0 in non-interactive mode by passing a prompt directly.

opengpt0 run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

opengpt0 run Explain the use of context in Go

You can also attach to a running opengpt0 serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
opengpt0 serve

# In another terminal, run commands that attach to it
opengpt0 run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
--command		The command to run, use message for args
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--fork		Fork the session when continuing (use with --continue or --session)
--share		Share the session
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--file	-f	File(s) to attach to message
--format		Format: default (formatted) or json (raw JSON events)
--title		Title for the session (uses truncated prompt if no value provided)
--attach		Attach to a running opengpt0 server (e.g., http://localhost:4096)
--password	-p	Basic auth password (defaults to OPENGPT0_SERVER_PASSWORD)
--username	-u	Basic auth username (defaults to OPENGPT0_SERVER_USERNAME or opengpt0)
--dir		Directory to run in, or path on the remote server when attaching
--port		Port for the local server (defaults to random port)
--variant		Model variant (provider-specific reasoning effort)
--thinking		Show thinking blocks
--dangerously-skip-permissions		Auto-approve permissions that are not explicitly denied (dangerous!)

---

serve

Start a headless OpenGPT0 server for API access. Check out the server docs for the full HTTP interface.

opengpt0 serve

This starts an HTTP server that provides API access to opengpt0 functionality without the TUI interface. Set OPENGPT0_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opengpt0).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--mdns-domain	Custom mDNS domain name
--cors	Additional browser origin(s) to allow CORS

---

session

Manage OpenGPT0 sessions.

opengpt0 session [command]

---

list

List all OpenGPT0 sessions.

opengpt0 session list

Flags

Flag	Short	Description
--max-count	-n	Limit to N most recent sessions
--format		Output format: table or json (table)

---

delete

Delete an OpenGPT0 session.

opengpt0 session delete <sessionID>

---

stats

Show token and usage statistics for your OpenGPT0 sessions.

opengpt0 stats

Flags

Flag	Description
--days	Show stats for the last N days (all time)
--tools	Number of tools to show (all)
--models	Show model usage breakdown (hidden by default). Pass a number to show top N
--project	Filter by project (all projects, empty string: current project)

---

export

Export session data as JSON.

opengpt0 export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

Flags

Flag	Description
--sanitize	Redact sensitive transcript/file data

---

import

Import session data from a JSON file or OpenGPT0 share URL.

opengpt0 import <file>

You can import from a local file or an OpenGPT0 share URL.

opengpt0 import session.json
opengpt0 import https://opengpt0.com/s/abc123

---

web

Start a headless OpenGPT0 server with a web interface.

opengpt0 web

This starts an HTTP server and opens a web browser to access OpenGPT0 through a web interface. Set OPENGPT0_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opengpt0).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--mdns-domain	Custom mDNS domain name
--cors	Additional browser origin(s) to allow CORS

---

plugin

Install a plugin and update your config.

opengpt0 plugin <module>

Or use the alias.

opengpt0 plug <module>

Flags

Flag	Short	Description
--global	-g	Install in global config
--force	-f	Replace existing plugin version

---

pr

Fetch and checkout a GitHub PR branch, then run OpenGPT0.

opengpt0 pr <number>

---

db

Database tools.

opengpt0 db [query]

Flags

Flag	Description
--format	Output format: json or tsv

---

path

Print the database path.

opengpt0 db path

---

debug

Debugging and troubleshooting tools.

opengpt0 debug [command]

---

uninstall

Uninstall OpenGPT0 and remove all related files.

opengpt0 uninstall

Flags

Flag	Short	Description
--keep-config	-c	Keep configuration files
--keep-data	-d	Keep session data and snapshots
--dry-run		Show what would be removed without removing
--force	-f	Skip confirmation prompts

---

upgrade

Updates opengpt0 to the latest version or a specific version.

opengpt0 upgrade [target]

To upgrade to the latest version.

opengpt0 upgrade

To upgrade to a specific version.

opengpt0 upgrade v0.1.48

Flags

Flag	Short	Description
--method	-m	The installation method that was used; curl, npm, pnpm, bun, brew

---

Global Flags

The opengpt0 CLI takes the following global flags.

Flag	Short	Description
--help	-h	Display help
--version	-v	Print version number
--print-logs		Print logs to stderr
--log-level		Log level (DEBUG, INFO, WARN, ERROR)
--pure		Run without external plugins

---

Environment variables

OpenGPT0 can be configured using environment variables.

Variable	Type	Description
OPENGPT0_AUTO_SHARE	boolean	Automatically share sessions
OPENGPT0_GIT_BASH_PATH	string	Path to Git Bash executable on Windows
OPENGPT0_CONFIG	string	Path to config file
OPENGPT0_TUI_CONFIG	string	Path to TUI config file
OPENGPT0_CONFIG_DIR	string	Path to config directory
OPENGPT0_CONFIG_CONTENT	string	Inline json config content
OPENGPT0_DISABLE_AUTOUPDATE	boolean	Disable automatic update checks
OPENGPT0_DISABLE_PRUNE	boolean	Disable pruning of old data
OPENGPT0_DISABLE_TERMINAL_TITLE	boolean	Disable automatic terminal title updates
OPENGPT0_PERMISSION	string	Inlined json permissions config
OPENGPT0_DISABLE_DEFAULT_PLUGINS	boolean	Disable default plugins
OPENGPT0_DISABLE_LSP_DOWNLOAD	boolean	Disable automatic LSP server downloads
OPENGPT0_ENABLE_EXPERIMENTAL_MODELS	boolean	Enable experimental model entries
OPENGPT0_DISABLE_AUTOCOMPACT	boolean	Disable automatic context compaction
OPENGPT0_DISABLE_CLAUDE_CODE	boolean	Disable reading from .claude (prompt + skills)
OPENGPT0_DISABLE_CLAUDE_CODE_PROMPT	boolean	Disable reading ~/.claude/CLAUDE.md
OPENGPT0_DISABLE_CLAUDE_CODE_SKILLS	boolean	Disable loading .claude/skills
OPENGPT0_DISABLE_MODELS_FETCH	boolean	Disable fetching model metadata from remote sources
OPENGPT0_DISABLE_MOUSE	boolean	Disable mouse capture in the TUI
OPENGPT0_FAKE_VCS	string	Fake VCS provider for testing purposes
OPENGPT0_CLIENT	string	Client identifier (defaults to cli)
OPENGPT0_ENABLE_EXA	boolean	Enable Exa web search tools
OPENGPT0_SERVER_PASSWORD	string	Enable basic auth for serve/web
OPENGPT0_SERVER_USERNAME	string	Override basic auth username (default opengpt0)
OPENGPT0_MODELS_URL	string	Custom URL for model metadata configuration

---

Experimental

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
OPENGPT0_EXPERIMENTAL	boolean	Enable the experimental umbrella flag
OPENGPT0_EXPERIMENTAL_ICON_DISCOVERY	boolean	Enable icon discovery
OPENGPT0_EXPERIMENTAL_DISABLE_COPY_ON_SELECT	boolean	Disable copy on select in TUI
OPENGPT0_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS	number	Default timeout for bash commands in ms
OPENGPT0_EXPERIMENTAL_OUTPUT_TOKEN_MAX	number	Max output tokens for LLM responses
OPENGPT0_EXPERIMENTAL_FILEWATCHER	boolean	Enable file watcher for entire dir
OPENGPT0_EXPERIMENTAL_OXFMT	boolean	Enable oxfmt formatter
OPENGPT0_EXPERIMENTAL_LSP_TOOL	boolean	Enable experimental LSP tool
OPENGPT0_EXPERIMENTAL_DISABLE_FILEWATCHER	boolean	Disable file watcher
OPENGPT0_EXPERIMENTAL_EXA	boolean	Enable experimental Exa features
OPENGPT0_EXPERIMENTAL_LSP_TY	boolean	Enable TY LSP for python files
OPENGPT0_EXPERIMENTAL_PLAN_MODE	boolean	Enable plan mode
OPENGPT0_EXPERIMENTAL_BACKGROUND_SUBAGENTS	boolean	Enable background subagent tasks
OPENGPT0_EXPERIMENTAL_EVENT_SYSTEM	boolean	Enable experimental event system
OPENGPT0_EXPERIMENTAL_NATIVE_LLM	boolean	Enable native LLM request path
OPENGPT0_EXPERIMENTAL_PARALLEL	boolean	Enable parallel web search execution
OPENGPT0_EXPERIMENTAL_SCOUT	boolean	Enable Scout subagent
OPENGPT0_EXPERIMENTAL_WORKSPACES	boolean	Enable workspace support