AI coding agent for the terminal - understands your codebase, edits files, runs commands, coordinates subagents. One MarsAI account, whole model catalog, device OAuth: no key handling.
Mars CLI (mars) is an AI coding agent for the terminal. It understands your codebase, edits files, runs commands, and coordinates subagents — powered by the MarsAI model network (marsai.click), with a free-model pool, automatic failover, and a background service architecture.
First run: launch mars in any project directory. If no MarsAI account is connected yet, a browser-based device sign-in opens automatically — approve once and you're in. No config files needed.
cd my-project
mars
Update later with mars upgrade (or the /update slash command inside the TUI). Auto-update is on by default.
Features
MarsAI model network
One integration, many models. A single MarsAI account provides the whole catalog — Claude, GLM, Kimi, Diffusion, and more — refreshed live from the endpoint. No per-provider API keys.
Real model names. The picker shows the endpoint's actual model IDs.
Free and paid tiers. Every model is tagged free or paid. Free models sort last in the picker so paid models are visible first.
/healthcheck times a minimal generation per model (server-side, concurrency 5) and shows which models are actually alive and fast.
Free pool + automatic fallback
Models whose ID contains subagent or free form a pool. Spawned subagents (including Explore) round-robin across it — subagent work burns free capacity by default.
If a model dies mid-generation (provider busy, quota, 5xx), the runner fails fast and escalates: next pool model → paid MarsAI models. No long retry waits on dead providers.
Pool matching skips deprecated catalog entries.
Explore agent
Built-in read-only file-search specialist. Always runs on free pool models with edit tools denied.
Subagent tools
Spawn subagents for research or parallel work; optionally run in the background and get notified on completion.
Live Subagents sidebar panel: per-model rows with a green ✓ while a job is actively running on that model, done markers when idle, ×N count for parallel jobs on one model.
Nested spawns are depth-limited for safety.
Sidebar
Right-hand live panel: account info, token usage (session total + last response, main model only), agent activity, subagent pool activity, and the fastest models by measured latency.
Background service
A single background server hosts all sessions; TUIs attach to it. Multiple projects/directories share one service (default port 49474, coexists with other tooling).
Broken/stale registered services self-heal on launch (automatic replace, no manual kill needed).
Restart-safe: sessions, credentials, and model state persist across upgrades.
Safety & permissions
Explicit permission system for edits and command execution; configurable allow/deny rules.
Plan mode (read-only) built in.
Auto sign-in gate: if a stored credential dies (expired/revoked), the next launch re-runs sign-in instead of failing silently.
Auto-update
Default policy auto: the CLI keeps itself current. On Windows, the updater safely parks a running executable aside before swapping (no EBUSY failures).
CLI commands
Syntax: mars [command] [flags]. Run mars --help or mars <command> --help for the live list.
Core
Command
Description
mars (no command)
Launch the interactive TUI in the current directory
mars [directory]
Launch the TUI in a specific directory
mars -c
Continue the most recent session
mars -s <sessionID>
Continue (or create) a specific session
mars --prompt "..."
Start with an initial prompt
mars run
Run a prompt non-interactively (scripts/CI)
mars serve
Run a headless server
mars pair
Pair the CLI with a web/desktop client
Sessions
Command
Description
mars session list
List sessions
mars session export
Export a session
mars session import
Import a session
mars session delete
Delete a session
Auth
Command
Description
mars auth login
Sign in to an integration (browser/device flow)
mars auth logout
Sign out
mars auth list
Show authenticated integrations
mars auth switch
Switch active account/credential
mars auth export
Export credentials
mars auth import
Import credentials
Models & config
Command
Description
mars models
List available models
mars agents
List agents
mars config list
List configuration sources
mars config get / set / unset
Read and write configuration values
mars paths
Show config/data/log paths
mars reload
Reload configuration
Service
Command
Description
mars service start
Start the background server
mars service stop
Stop the background server
mars service restart
Restart the background server
mars service status
Show background server status
mars service get / set / unset
Service settings (e.g. port)
Extensions
Command
Description
mars mcp list
List configured MCP servers and status
mars mcp add
Add an MCP server
mars mcp auth / logout
MCP server authentication
mars plugin list
List installed plugins
mars plugin add / remove / update
Manage plugins
mars plugin check
Check plugin health
Maintenance
Command
Description
mars upgrade [version] (alias: update)
Upgrade to latest or a specific version
mars uninstall
Uninstall the CLI (keeps sessions/config)
mars stats
Usage statistics
mars api <operation or METHOD path>
Call the running server's API directly
mars acp
Start an Agent Client Protocol server
mars debug
Debug utilities
Global flags
Flag
Description
--continue, -c
Continue the last session
--session, -s <id>
Continue/create a session by ID
--prompt <text>
Initial prompt
--print-logs
Print logs to stderr
--standalone
Run with a private server instead of the background service
--server <url>
Connect to a specific server URL
--auto
Auto-approve non-denied permissions
Slash commands (inside the TUI)
Command
Description
/new
New session
/sessions (aliases: /resume, /continue)
Switch session
/clear
Clear the current session
/open (aliases: /projects, /project)
Open another project
/models
Model picker (paid first, free pool last, favorites + speed ranking)
/agents
Agent picker
/mcps
MCP servers
/variants (aliases: /thinking, /effort)
Model variant / reasoning effort
/connect
Manage connected integrations
/healthcheck
Probe model latency and availability live
/settings
Settings
/status
Session/service status
/update
Update Mars CLI
/pair
Pair with web/desktop
/restart
Restart the background service
/reload
Reload configuration
/themes
Theme picker
/debug
Debug tools
/cd <dir>
Change directory
/help
Help
/exit
Quit
How it works
mars (TUI) ──┐
mars (TUI) ──┼──> background service (port 49474) ──> MarsAI API (marsai.click/v1)
mars run ────┘ │
├── sessions, credentials (SQLite, encrypted)
├── model catalog (live refresh, free/paid tags)
└── healthcheck probes (server-side, credentials never leave the service)
One service, many clients. Every TUI, mars run, and API call attaches to the same background service; projects stay isolated per directory.
Credential safety. OAuth tokens live in the service's encrypted store and are refreshed in a single-flight lock — multiple open projects never race token rotation.
Model truth. The model catalog mirrors the MarsAI endpoint verbatim; availability changes on the server appear in the picker within a minute.
