CLI
quantumcoderxyz CLI options and commands.
The quantumcoderxyz CLI by default starts the TUI when run without any arguments.
quantumcoderxyzBut it also accepts commands as documented on this page. This allows you to interact with quantumcoderxyz programmatically.
quantumcoderxyz run "Explain how closures work in JavaScript"tui
Start the quantumcoderxyz terminal user interface.
quantumcoderxyz [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 | |
--auto | Auto-approve permissions that are not explicitly denied | |
--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 quantumcoderxyz CLI also has the following commands.
agent
Manage agents for quantumcoderxyz.
quantumcoderxyz agent [command]create
Create a new agent with custom configuration.
quantumcoderxyz agent createThis 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 | Config directory whose agents/ subdirectory receives the file (defaults to global or .quantumcoderxyz 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.
quantumcoderxyz agent listattach
Attach a terminal to an already running quantumcoderxyz backend server started via serve or web commands.
quantumcoderxyz attach [url]This allows using the TUI with a remote quantumcoderxyz backend. For example:
# Start the backend server for web/mobile accessquantumcoderxyz web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backendquantumcoderxyz attach http://10.20.30.40:4096Flags
| 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 quantumcoderxyz_SERVER_PASSWORD) |
--username | -u |
Basic auth username (defaults to quantumcoderxyz_SERVER_USERNAME or quantumcoderxyz) |
auth
Command to manage credentials and login for providers.
quantumcoderxyz auth [command]login
quantumcoderxyz is powered by the provider list at Models.dev, so you can use quantumcoderxyz auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/quantumcoderxyz/auth.json.
quantumcoderxyz auth loginWhen quantumcoderxyz starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.
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 all the authenticated providers as stored in the credentials file.
quantumcoderxyz auth listOr the short version.
quantumcoderxyz auth lslogout
Logs you out of a provider by clearing it from the credentials file.
quantumcoderxyz auth logoutcompletion
Generate a shell completion script.
quantumcoderxyz completiongithub
Manage the GitHub agent for repository automation.
quantumcoderxyz github [command]install
Install the GitHub agent in your repository.
quantumcoderxyz github installThis 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.
quantumcoderxyz github runFlags
| Flag | Description |
|---|---|
--event | GitHub mock event to run the agent for |
--token | GitHub personal access token |
mcp
Manage Model Context Protocol servers.
quantumcoderxyz mcp [command]add
Add an MCP server to your configuration.
quantumcoderxyz mcp addThis command will guide you through adding either a local or remote MCP server.
list
List all configured MCP servers and their connection status.
quantumcoderxyz mcp listOr use the short version.
quantumcoderxyz mcp lsauth
Authenticate with an OAuth-enabled MCP server.
quantumcoderxyz 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.
quantumcoderxyz mcp auth listOr use the short version.
quantumcoderxyz mcp auth lslogout
Remove OAuth credentials for an MCP server.
quantumcoderxyz mcp logout [name]debug
Debug OAuth connection issues for an MCP server.
quantumcoderxyz mcp debug <name>models
List all available models from configured providers.
quantumcoderxyz models [provider]This command displays all models available across your configured providers in the format provider/model.
This is useful for figuring out the exact model name to use in your config.
You can optionally pass a provider ID to filter models by that provider.
quantumcoderxyz models anthropicFlags
| Flag | Description |
|---|---|
--refresh | Refresh the models cache from models.dev |
--verbose | Use more verbose model output (includes metadata like costs) |
Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in quantumcoderxyz.
quantumcoderxyz models --refreshrun
Run quantumcoderxyz in non-interactive mode by passing a prompt directly.
quantumcoderxyz run [message..]This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
quantumcoderxyz run Explain the use of context in GoYou can also attach to a running quantumcoderxyz serve instance to avoid MCP server cold boot times on every run:
# Start a headless server in one terminalquantumcoderxyz serve
# In another terminal, run commands that attach to itquantumcoderxyz 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) |
|
--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 quantumcoderxyz server (e.g., http://localhost:4096) | |
--password | -p |
Basic auth password (defaults to quantumcoderxyz_SERVER_PASSWORD) |
--username | -u |
Basic auth username (defaults to quantumcoderxyz_SERVER_USERNAME or quantumcoderxyz) |
--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 | |
--auto | Auto-approve permissions that are not explicitly denied |
serve
Start a headless quantumcoderxyz server for API access. Check out the server docs for the full HTTP interface.
quantumcoderxyz serveThis starts an HTTP server that provides API access to quantumcoderxyz functionality without the TUI interface. Set quantumcoderxyz_SERVER_PASSWORD to enable HTTP basic auth (username defaults to quantumcoderxyz).
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 quantumcoderxyz sessions.
quantumcoderxyz session [command]list
List all quantumcoderxyz sessions.
quantumcoderxyz session listFlags
| Flag | Short | Description |
|---|---|---|
--max-count | -n |
Limit to N most recent sessions |
--format | Output format: table or json (table) |
delete
Delete an quantumcoderxyz session.
quantumcoderxyz session delete <sessionID>stats
Show token usage and cost statistics for your quantumcoderxyz sessions.
quantumcoderxyz statsFlags
| 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.
quantumcoderxyz 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.
quantumcoderxyz import <file>quantumcoderxyz import session.jsonweb
Start a headless quantumcoderxyz server with a web interface.
quantumcoderxyz webThis starts an HTTP server and opens a web browser to access quantumcoderxyz through a web interface. Set quantumcoderxyz_SERVER_PASSWORD to enable HTTP basic auth (username defaults to quantumcoderxyz).
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 |
acp
Start an ACP (Agent Client Protocol) server.
quantumcoderxyz acpThis command starts an ACP server that communicates via stdin/stdout using nd-JSON.
Flags
| Flag | Description |
|---|---|
--cwd | Working directory |
--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.
quantumcoderxyz plugin <module>Or use the alias.
quantumcoderxyz 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 quantumcoderxyz.
quantumcoderxyz pr <number>db
Database tools.
quantumcoderxyz db [query]Flags
| Flag | Description |
|---|---|
--format | Output format: json or tsv |
path
Print the database path.
quantumcoderxyz db pathdebug
Debugging and troubleshooting tools.
quantumcoderxyz debug [command]agent
Show a loaded agent’s configuration. Use quantumcoderxyz agent list to list all agents.
quantumcoderxyz debug agent buildconfig
Show the resolved configuration.
quantumcoderxyz debug configpaths
Show global paths (data, config, cache, state).
quantumcoderxyz debug pathsThis prints all global paths. To print the database path, use:
quantumcoderxyz db pathOther debug commands
| Command | Description |
|---|---|
quantumcoderxyz debug info |
Show the version, OS, terminal, and configured plugins |
quantumcoderxyz debug skill |
List available skills |
quantumcoderxyz debug scrap |
List known projects |
quantumcoderxyz debug file list <path> |
List files in a directory |
quantumcoderxyz debug file read <path> |
Read a file as JSON with base64-encoded content |
quantumcoderxyz debug file search <query> |
Search file paths |
quantumcoderxyz debug rg files |
List files using ripgrep; accepts --glob and --limit |
quantumcoderxyz debug rg search <pattern> |
Search file contents; accepts --glob and --limit |
quantumcoderxyz debug lsp diagnostics <file> |
Get LSP diagnostics for a file |
quantumcoderxyz debug lsp symbols <query> |
Search workspace symbols |
quantumcoderxyz debug lsp document-symbols <uri> |
Get symbols from a document |
quantumcoderxyz debug snapshot track |
Track the current snapshot state |
quantumcoderxyz debug snapshot patch <hash> |
Show changed files for a snapshot hash |
quantumcoderxyz debug snapshot diff <hash> |
Show the diff for a snapshot hash |
quantumcoderxyz debug startup |
Print startup timing |
uninstall
Uninstall quantumcoderxyz and remove all related files.
quantumcoderxyz uninstallFlags
| 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 quantumcoderxyz to the latest version or a specific version.
quantumcoderxyz upgrade [target]To upgrade to the latest version.
quantumcoderxyz upgradeTo upgrade to a specific version.
quantumcoderxyz upgrade v0.1.48To upgrade to quantumcoderxyz 2 and remove quantumcoderxyz 1:
quantumcoderxyz upgrade --majorFlags
| Flag | Short | Description |
|---|---|---|
--method | -m |
The installation method that was used; curl, npm, pnpm, bun, brew |
--major | Upgrade to quantumcoderxyz 2 and remove quantumcoderxyz 1 |
Global Flags
The quantumcoderxyz 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
quantumcoderxyz can be configured using environment variables.
| Variable | Type | Description |
|---|---|---|
quantumcoderxyz_GIT_BASH_PATH |
string | Path to Git Bash executable on Windows |
quantumcoderxyz_CONFIG |
string | Path to config file |
quantumcoderxyz_TUI_CONFIG |
string | Path to TUI config file |
quantumcoderxyz_CONFIG_DIR |
string | Path to config directory |
quantumcoderxyz_CONFIG_CONTENT |
string | Inline json config content |
quantumcoderxyz_DISABLE_AUTOUPDATE |
boolean | Disable automatic update checks |
quantumcoderxyz_DISABLE_PRUNE |
boolean | Disable pruning of old data |
quantumcoderxyz_DISABLE_TERMINAL_TITLE |
boolean | Disable automatic terminal title updates |
quantumcoderxyz_PERMISSION |
string | Inlined json permissions config |
quantumcoderxyz_DISABLE_DEFAULT_PLUGINS |
boolean | Disable default plugins |
quantumcoderxyz_DISABLE_LSP_DOWNLOAD |
boolean | Disable automatic LSP server downloads |
quantumcoderxyz_ENABLE_EXPERIMENTAL_MODELS |
boolean | Enable experimental models |
quantumcoderxyz_DISABLE_AUTOCOMPACT |
boolean | Disable automatic context compaction |
quantumcoderxyz_DISABLE_CLAUDE_CODE |
boolean | Disable reading from .claude (prompt + skills) |
quantumcoderxyz_DISABLE_CLAUDE_CODE_PROMPT |
boolean | Disable reading ~/.claude/CLAUDE.md |
quantumcoderxyz_DISABLE_CLAUDE_CODE_SKILLS |
boolean | Disable loading .claude/skills |
quantumcoderxyz_DISABLE_MODELS_FETCH |
boolean | Disable fetching models from remote sources |
quantumcoderxyz_DISABLE_MOUSE |
boolean | Disable mouse capture in the TUI |
quantumcoderxyz_FAKE_VCS |
string | Fake VCS provider for testing purposes |
quantumcoderxyz_CLIENT |
string | Client identifier (defaults to cli) |
quantumcoderxyz_ENABLE_EXA |
boolean | Enable Exa web search tools |
quantumcoderxyz_ENABLE_PARALLEL |
boolean | Enable Parallel web search tools |
quantumcoderxyz_SERVER_PASSWORD |
string | Enable basic auth for serve/web |
quantumcoderxyz_SERVER_USERNAME |
string | Override basic auth username (default quantumcoderxyz) |
quantumcoderxyz_MODELS_URL |
string | Custom URL for fetching models configuration |
quantumcoderxyz_MODELS_PATH |
string | Load the model catalog from a local JSON file |
quantumcoderxyz_DB |
string | Database path; relative paths resolve under the data directory |
quantumcoderxyz_PURE |
boolean | Run without external plugins, like --pure |
quantumcoderxyz_DISABLE_PROJECT_CONFIG |
boolean | Disable project configuration and project instruction files |
quantumcoderxyz_DISABLE_EXTERNAL_SKILLS |
boolean | Disable skill discovery in .claude and .agents directories |
quantumcoderxyz_DISABLE_EMBEDDED_WEB_UI |
boolean | Disable the bundled web UI and use the remote UI fallback |
quantumcoderxyz_DISABLE_FFF |
boolean | Use ripgrep instead of the native file finder; enabled by default on Windows |
quantumcoderxyz_ENABLE_QUESTION_TOOL |
boolean | Enable the question tool for clients other than the CLI, app, and desktop |
quantumcoderxyz_ALWAYS_NOTIFY_UPDATE |
boolean | Show update notifications even without a newer version |
quantumcoderxyz_SHOW_TTFD |
boolean | Show time-to-first-delta timing |
quantumcoderxyz_LOG_LEVEL |
string | Log level: DEBUG, INFO, WARN, or ERROR |
quantumcoderxyz_PRINT_LOGS |
string | Set to 1 to also print logs to stderr |
quantumcoderxyz_AUTO_HEAP_SNAPSHOT |
boolean | Capture a heap snapshot when memory usage exceeds 2 GiB |
Experimental
These environment variables enable experimental features that may change or be removed.
| Variable | Type | Description |
|---|---|---|
quantumcoderxyz_EXPERIMENTAL |
boolean | Enable the experimental umbrella flag |
quantumcoderxyz_EXPERIMENTAL_ICON_DISCOVERY |
boolean | Enable icon discovery |
quantumcoderxyz_EXPERIMENTAL_DISABLE_COPY_ON_SELECT |
boolean | Disable copy on select in TUI |
quantumcoderxyz_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS |
number | Default timeout for bash commands in ms |
quantumcoderxyz_EXPERIMENTAL_OUTPUT_TOKEN_MAX |
number | Max output tokens for LLM responses |
quantumcoderxyz_EXPERIMENTAL_FILEWATCHER |
boolean | Enable file watcher for entire dir |
quantumcoderxyz_EXPERIMENTAL_OXFMT |
boolean | Enable oxfmt formatter |
quantumcoderxyz_EXPERIMENTAL_LSP_TOOL |
boolean | Enable experimental LSP tool |
quantumcoderxyz_EXPERIMENTAL_DISABLE_FILEWATCHER |
boolean | Disable file watcher |
quantumcoderxyz_EXPERIMENTAL_EXA |
boolean | Enable experimental Exa features |
quantumcoderxyz_EXPERIMENTAL_LSP_TY |
boolean | Enable TY LSP for python files |
quantumcoderxyz_EXPERIMENTAL_CODE_MODE |
boolean | Enable code-mode tool execution |
quantumcoderxyz_EXPERIMENTAL_WEBSOCKETS |
boolean | Use WebSockets for OpenAI requests |
quantumcoderxyz_EXPERIMENTAL_PLAN_MODE |
boolean | Enable plan mode |
quantumcoderxyz_EXPERIMENTAL_BACKGROUND_SUBAGENTS |
boolean | Enable background subagent tasks |
quantumcoderxyz_EXPERIMENTAL_EVENT_SYSTEM |
boolean | Enable experimental event system |
quantumcoderxyz_EXPERIMENTAL_NATIVE_LLM |
boolean | Enable native LLM request path |
quantumcoderxyz_EXPERIMENTAL_PARALLEL |
boolean | Enable parallel web search execution |
quantumcoderxyz_EXPERIMENTAL_WORKSPACES |
boolean | Enable workspace support |