Commands Reference

Complete reference for every codecli command. Commands are organized into categories: core interactions, authentication, agent management, MCP integration, session management, and advanced utilities.

✓Tip

Use codecli COMMAND --help at any time to see inline help for a specific command.

Core Commands

These are the primary interaction modes. If no subcommand is given, tui is the default.

codecli tui

Launch the full terminal UI. This is the default command when codecli is run with no subcommand. The TUI provides a rich interactive interface built with Solid.js, including 19 context providers, a kanban board, obsidian vault integration, split-panel management views, and more.

bash

codecli tui [options]
codecli              # identical to codecli tui

Flag	Type	Default	Description
--model MODEL	string	auto	Model to use (e.g. claude-sonnet-4-20250514, gpt-4o)
--agent NAME	string	---	Load a saved agent configuration by name
--variant VARIANT	string	---	Model variant preset (fast, smart, reasoning)
--thinking	boolean	false	Enable extended thinking / chain-of-thought mode
--continue	boolean	false	Resume the most recent session
--session ID	string	---	Resume a specific session by ID
--resume	boolean	false	Alias for --continue
--title TITLE	string	---	Set a title for the new session
--add-dir PATH	string	---	Add a directory to the workspace (repeatable)
--append-system-prompt TEXT	string	---	Append text to the system prompt
--bare	boolean	false	Skip project config and default plugins
--enable-auto-mode	boolean	false	Enable automatic tool execution without confirmation
--mainframe	boolean	false	Launch in mainframe mode (multi-terminal control)
--compact-threshold N	number	auto	Token threshold for auto-compaction
--preset NAME	string	---	Load a preset configuration profile
--remote	boolean	false	Connect to a remote codecli server
--background	boolean	false	Run in background / daemon mode

codecli chat

Start an interactive chat session in the terminal (no TUI). Useful for scripting, pipes, and minimal environments. Reads from stdin if input is piped.

bash

codecli chat [options]
echo "Explain this function" | codecli chat
codecli chat --model gpt-4o --raw

Flag	Type	Default	Description
--model MODEL	string	auto	Model to use
--raw	boolean	false	Output raw text without formatting
--stream / --no-stream	boolean	true	Stream response tokens in real time
--format FORMAT	string	text	Output format: text, json, markdown
--continue	boolean	false	Continue the most recent session
--session ID	string	---	Resume a specific session
--title TITLE	string	---	Set session title
--append-system-prompt TEXT	string	---	Append to system prompt

codecli run

Execute a single prompt non-interactively. Prints the response and exits. Ideal for scripting, CI pipelines, and batch processing.

bash

codecli run "Explain what this project does"
codecli run --model gpt-4o --format json "List all TODO comments"
cat error.log | codecli run "Diagnose this error"

Flag	Type	Default	Description
--model MODEL	string	auto	Model to use
--raw	boolean	false	Output raw text without formatting
--stream / --no-stream	boolean	false	Stream response (default off for run)
--format FORMAT	string	text	Output format: text, json, markdown
--timeout MS	number	120000	Timeout in milliseconds
--max-turns N	number	unlimited	Maximum agent turns before stopping

codecli repl

Start a Read-Eval-Print Loop with a simpler interface than the TUI. Supports multi-line input with Shift+Enter.

bash

codecli repl [options]
codecli repl --model deepseek-v3

Flag	Type	Default	Description
--model MODEL	string	auto	Model to use
--continue	boolean	false	Continue the most recent session
--session ID	string	---	Resume a specific session

Auth Commands

Manage authentication credentials for Polysystems and AI providers.

Authenticate with the Polysystems platform. Opens a browser for OAuth flow or accepts an API token directly.

bash

codecli auth login
codecli auth login --token sk-poly-abc123...
codecli auth login --provider github

Flag	Type	Default	Description
--token TOKEN	string	---	Authenticate with an API token directly
--provider PROVIDER	string	auto	OAuth provider: github, google
--no-open	boolean	false	Print the auth URL instead of opening browser

codecli auth logout

Clear stored authentication credentials.

bash

codecli auth logout

codecli auth list

Show the current authentication status and stored credentials.

bash

codecli auth list

codecli provider add

Add an AI provider with its API key. The provider becomes available for model routing.

bash

codecli provider add openai --api-key sk-...
codecli provider add anthropic --api-key sk-ant-...
codecli provider add ollama --base-url http://localhost:11434

Flag	Type	Default	Description
--api-key KEY	string	---	API key for the provider
--base-url URL	string	---	Custom base URL (for self-hosted providers)
--name NAME	string	---	Custom name for this provider instance

codecli provider list

List all configured AI providers and their status.

bash

codecli provider list

codecli provider models

List all available models across configured providers.

bash

codecli provider models
codecli provider models --provider openai

Flag	Type	Default	Description
--provider NAME	string	all	Filter models by provider
--format FORMAT	string	table	Output format: table, json

Agent Commands

Manage agent configurations for specialized workflows.

codecli agent create

Create a new agent configuration. Opens an interactive prompt to set the system prompt, model, tools, and permissions.

bash

codecli agent create
codecli agent create --name "code-reviewer" --model claude-sonnet-4-20250514

Flag	Type	Default	Description
--name NAME	string	---	Agent name (required in non-interactive mode)
--model MODEL	string	auto	Default model for this agent
--system-prompt TEXT	string	---	System prompt for this agent
--tools LIST	string	all	Comma-separated list of enabled tools
--permission MODE	string	ask	Default permission mode: ask, auto, deny

codecli agent list

List all saved agent configurations.

bash

codecli agent list

MCP Commands

Manage Model Context Protocol server connections.

codecli mcp add

Add an MCP server to the configuration. Supports stdio and HTTP (SSE) transports.

bash

codecli mcp add my-server --command "npx -y @some/mcp-server"
codecli mcp add remote-server --url https://example.com/mcp
codecli mcp add filesystem --command "npx @modelcontextprotocol/server-filesystem /path" --env ROOT=/path

Flag	Type	Default	Description
--command CMD	string	---	Command to launch the MCP server (stdio transport)
--url URL	string	---	URL for HTTP/SSE transport
--transport TYPE	string	auto	Transport type: stdio, http, sse
--env KEY=VALUE	string	---	Environment variable (repeatable)
--header KEY:VALUE	string	---	HTTP header for SSE transport (repeatable)
--disabled	boolean	false	Add the server in disabled state

codecli mcp list

List all configured MCP servers and their connection status.

bash

codecli mcp list

codecli mcp auth

Authenticate with an MCP server that requires OAuth or token-based auth.

bash

codecli mcp auth my-server

codecli mcp logout

Clear authentication credentials for an MCP server.

bash

codecli mcp logout my-server

codecli mcp debug

Run an MCP server in debug mode. Shows all JSON-RPC messages exchanged.

bash

codecli mcp debug my-server

codecli mcp-server

Start codecli itself as an MCP server, exposing 36+ tools to other applications. Supports stdio (default) and HTTP transports.

bash

codecli mcp-server                    # stdio transport
codecli mcp-server -t http -p 4097   # HTTP transport on port 4097

Flag	Short	Type	Default	Description
--transport	-t	string	stdio	Transport: stdio, http, sse
--port	-p	number	4097	Port for HTTP transport
--hostname	-h	string	localhost	Bind hostname
--mdns		boolean	false	Advertise via mDNS/Bonjour

ACP

Agent Communication Protocol for IDE integration.

codecli acp

Start the ACP adapter that enables IDE integration (VS Code, JetBrains, Neovim). The ACP protocol bridges between the IDE and the codecli agent.

bash

codecli acp
codecli acp --port 4517
codecli acp --stdio

Flag	Type	Default	Description
--port N	number	4517	TCP port for ACP server
--stdio	boolean	false	Use stdio transport instead of TCP
--hostname HOST	string	localhost	Bind hostname

Session Commands

Manage persistent sessions with history, context, and export capabilities.

codecli session

List all sessions with metadata (title, model, date, turn count).

bash

codecli session
codecli session --limit 20

Flag	Type	Default	Description
--limit N	number	50	Maximum sessions to list
--format FORMAT	string	table	Output format: table, json

codecli export

Export a session to a file. Supports multiple formats for archival or sharing.

bash

codecli export SESSION_ID
codecli export SESSION_ID --format json --output ./session.json
codecli export --latest --format markdown

Flag	Type	Default	Description
--format FORMAT	string	json	Output format: json, markdown, html, txt
--output PATH	string	stdout	Output file path
--latest	boolean	false	Export the most recent session
--include-tool-output	boolean	false	Include full tool call results

codecli import

Import a session from a previously exported file.

bash

codecli import ./session.json

codecli stats

Show usage statistics: total sessions, turns, tokens used, tool calls, and cost breakdown.

bash

codecli stats
codecli stats --since 2026-04-01
codecli stats --by-model

Flag	Type	Default	Description
--since DATE	string	---	Show stats since date (ISO 8601)
--by-model	boolean	false	Break down usage by model
--by-day	boolean	false	Break down usage by day
--format FORMAT	string	table	Output format: table, json

Advanced Commands

codecli serve

Start codecli as a persistent HTTP/WebSocket server. Other codecli instances can connect to it with --remote.

bash

codecli serve
codecli serve --port 8090 --hostname 0.0.0.0

Flag	Type	Default	Description
--port N	number	8090	Server port
--hostname HOST	string	localhost	Bind hostname
--mdns	boolean	false	Advertise via mDNS/Bonjour for discovery
--auth-token TOKEN	string	---	Require this token for connections

codecli connect

Connect to a running codecli server (started with codecli serve).

bash

codecli connect http://192.168.1.50:8090
codecli connect --mdns              # auto-discover via mDNS

Flag	Type	Default	Description
--auth-token TOKEN	string	---	Auth token for the remote server
--mdns	boolean	false	Auto-discover servers via mDNS

codecli attach

Attach to a running background codecli process. Useful when codecli was started with --background.

bash

codecli attach
codecli attach PID

codecli secrets

Manage secrets from the Polysystems vault directly in the CLI. Supports listing, getting, setting, and importing secrets.

bash

codecli secrets list
codecli secrets get DATABASE_URL
codecli secrets set API_KEY "sk-abc123"
codecli secrets import .env

Flag	Type	Default	Description
--vault ID	string	default	Target vault ID or name
--format FORMAT	string	table	Output format: table, json, env

codecli github

GitHub integration commands for managing repositories, issues, and pull requests.

bash

codecli github issues
codecli github pr list
codecli github pr checkout 123

Subcommand	Description
issues	List and manage repository issues
pr list	List pull requests
pr checkout N	Checkout a pull request branch
pr create	Create a new pull request
repo clone URL	Clone a repository

codecli datasets

Manage datasets for RAG (Retrieval-Augmented Generation) and fine-tuning.

bash

codecli datasets list
codecli datasets create --name "api-docs" --source ./docs
codecli datasets search "authentication flow"

Flag	Type	Default	Description
--name NAME	string	---	Dataset name
--source PATH	string	---	Source directory or file for ingestion
--format FORMAT	string	jsonl	Dataset format: jsonl, csv

codecli debug

Start an interactive debugging session. Shows verbose logging, tool execution traces, model request/response payloads, and performance metrics.

bash

codecli debug
codecli debug --verbose --trace-tools

Flag	Type	Default	Description
--verbose	boolean	false	Show all internal logging
--trace-tools	boolean	false	Log full tool call parameters and results
--trace-model	boolean	false	Log raw model API requests and responses
--log-file PATH	string	---	Write debug logs to file

codecli upgrade

Check for and install the latest version of codecli.

bash

codecli upgrade
codecli upgrade --check     # only check, do not install

Flag	Type	Default	Description
--check	boolean	false	Only check for updates, do not install
--force	boolean	false	Force reinstall even if already up to date
--version VERSION	string	latest	Install a specific version

codecli uninstall

Remove codecli from the system. Optionally clean up configuration and session data.

bash

codecli uninstall
codecli uninstall --purge   # remove all config and session data too

Flag	Type	Default	Description
--purge	boolean	false	Remove all config files, sessions, and cached data
--yes	boolean	false	Skip confirmation prompt

#Commands Reference

#Core Commands

#codecli tui

#codecli chat

#codecli run

#codecli repl

#Auth Commands

#codecli auth login

#codecli auth logout

#codecli auth list

#codecli provider add

#codecli provider list

#codecli provider models

#Agent Commands

#codecli agent create

#codecli agent list

#MCP Commands

#codecli mcp add

#codecli mcp list

#codecli mcp auth

#codecli mcp logout

#codecli mcp debug

#codecli mcp-server

#ACP

#codecli acp

#Session Commands

#codecli session

#codecli export

#codecli import

#codecli stats

#Advanced Commands

#codecli serve

#codecli connect

#codecli attach

#codecli secrets

#codecli github

#codecli datasets

#codecli debug

#codecli upgrade

#codecli uninstall

Commands Reference

Core Commands

codecli tui

codecli chat

codecli run

codecli repl

Auth Commands

codecli auth login

codecli auth logout

codecli auth list

codecli provider add

codecli provider list

codecli provider models

Agent Commands

codecli agent create

codecli agent list

MCP Commands

codecli mcp add

codecli mcp list

codecli mcp auth

codecli mcp logout

codecli mcp debug

codecli mcp-server

ACP

codecli acp

Session Commands

codecli session

codecli export

codecli import

codecli stats

Advanced Commands

codecli serve

codecli connect

codecli attach

codecli secrets

codecli github

codecli datasets

codecli debug

codecli upgrade

codecli uninstall