Skip to content
Newquantumcoderxyz v2 is now available

CLI

quantumcoderxyz CLI options and commands.

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

Terminal window
quantumcoderxyz

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

Terminal window
quantumcoderxyz run "Explain how closures work in JavaScript"

tui

Start the quantumcoderxyz terminal user interface.

Terminal window
quantumcoderxyz [project]

Flags

FlagShortDescription
--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.

Terminal window
quantumcoderxyz agent [command]

create

Create a new agent with custom configuration.

Terminal window
quantumcoderxyz 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
FlagShortDescription
--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.

Terminal window
quantumcoderxyz agent list

attach

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

Terminal window
quantumcoderxyz attach [url]

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

Terminal window
# Start the backend server for web/mobile access
quantumcoderxyz web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backend
quantumcoderxyz attach http://10.20.30.40:4096

Flags

FlagShortDescription
--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.

Terminal window
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.

Terminal window
quantumcoderxyz auth login

When 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
FlagShortDescription
--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.

Terminal window
quantumcoderxyz auth list

Or the short version.

Terminal window
quantumcoderxyz auth ls

logout

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

Terminal window
quantumcoderxyz auth logout

completion

Generate a shell completion script.

Terminal window
quantumcoderxyz completion

github

Manage the GitHub agent for repository automation.

Terminal window
quantumcoderxyz github [command]

install

Install the GitHub agent in your repository.

Terminal window
quantumcoderxyz 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.

Terminal window
quantumcoderxyz github run
Flags
FlagDescription
--eventGitHub mock event to run the agent for
--tokenGitHub personal access token

mcp

Manage Model Context Protocol servers.

Terminal window
quantumcoderxyz mcp [command]

add

Add an MCP server to your configuration.

Terminal window
quantumcoderxyz 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.

Terminal window
quantumcoderxyz mcp list

Or use the short version.

Terminal window
quantumcoderxyz mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

Terminal window
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.

Terminal window
quantumcoderxyz mcp auth list

Or use the short version.

Terminal window
quantumcoderxyz mcp auth ls

logout

Remove OAuth credentials for an MCP server.

Terminal window
quantumcoderxyz mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

Terminal window
quantumcoderxyz mcp debug <name>

models

List all available models from configured providers.

Terminal window
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.

Terminal window
quantumcoderxyz models anthropic

Flags

FlagDescription
--refreshRefresh the models cache from models.dev
--verboseUse 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.

Terminal window
quantumcoderxyz models --refresh

run

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

Terminal window
quantumcoderxyz run [message..]

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

Terminal window
quantumcoderxyz run Explain the use of context in Go

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

Terminal window
# Start a headless server in one terminal
quantumcoderxyz serve
# In another terminal, run commands that attach to it
quantumcoderxyz run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

FlagShortDescription
--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.

Terminal window
quantumcoderxyz serve

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

session

Manage quantumcoderxyz sessions.

Terminal window
quantumcoderxyz session [command]

list

List all quantumcoderxyz sessions.

Terminal window
quantumcoderxyz session list
Flags
FlagShortDescription
--max-count-n Limit to N most recent sessions
--format Output format: table or json (table)

delete

Delete an quantumcoderxyz session.

Terminal window
quantumcoderxyz session delete <sessionID>

stats

Show token usage and cost statistics for your quantumcoderxyz sessions.

Terminal window
quantumcoderxyz stats

Flags

FlagDescription
--daysShow stats for the last N days (all time)
--toolsNumber of tools to show (all)
--modelsShow model usage breakdown (hidden by default). Pass a number to show top N
--projectFilter by project (all projects, empty string: current project)

export

Export session data as JSON.

Terminal window
quantumcoderxyz export [sessionID]

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

Flags

FlagDescription
--sanitizeRedact sensitive transcript/file data

import

Import session data from a JSON file.

Terminal window
quantumcoderxyz import <file>
Terminal window
quantumcoderxyz import session.json

web

Start a headless quantumcoderxyz server with a web interface.

Terminal window
quantumcoderxyz web

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

Terminal window
quantumcoderxyz acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

FlagDescription
--cwdWorking directory
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

Terminal window
quantumcoderxyz plugin <module>

Or use the alias.

Terminal window
quantumcoderxyz plug <module>

Flags

FlagShortDescription
--global-g Install in global config
--force-f Replace existing plugin version

pr

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

Terminal window
quantumcoderxyz pr <number>

db

Database tools.

Terminal window
quantumcoderxyz db [query]

Flags

FlagDescription
--formatOutput format: json or tsv

path

Print the database path.

Terminal window
quantumcoderxyz db path

debug

Debugging and troubleshooting tools.

Terminal window
quantumcoderxyz debug [command]

agent

Show a loaded agent’s configuration. Use quantumcoderxyz agent list to list all agents.

Terminal window
quantumcoderxyz debug agent build

config

Show the resolved configuration.

Terminal window
quantumcoderxyz debug config

paths

Show global paths (data, config, cache, state).

Terminal window
quantumcoderxyz debug paths

This prints all global paths. To print the database path, use:

Terminal window
quantumcoderxyz db path

Other 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.

Terminal window
quantumcoderxyz uninstall

Flags

FlagShortDescription
--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.

Terminal window
quantumcoderxyz upgrade [target]

To upgrade to the latest version.

Terminal window
quantumcoderxyz upgrade

To upgrade to a specific version.

Terminal window
quantumcoderxyz upgrade v0.1.48

To upgrade to quantumcoderxyz 2 and remove quantumcoderxyz 1:

Terminal window
quantumcoderxyz upgrade --major

Flags

FlagShortDescription
--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.

FlagShortDescription
--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