MARS CLI, from first install to release publication.

mars setup

First-time machine preparation. It creates ~/.mars/, writes config, detects hardware, installs llama.cpp server artifacts, downloads local model bundles only after an exact displayed-plan acknowledgement, and leaves optional GitHub release credentials separate from ordinary setup.

Common flags

--skip-download, --download, --skip-github, --github, --test-mode, --dry-run, --install-dir, --inference local|cloud|defer, --local-bundle auto|local-cpu-q3|local-balanced-q4|local-quality-q8, --yes, --json, --plain.

Use when

You are installing MARS on a machine, changing local bundle profile, or repairing missing model/server state.

Download admission

Pending artifacts are stable-sorted with concrete bundle, immutable identity, exact bytes, license ID/URL, and terms/notice URLs. Interactive use confirms once; non-TTY and JSON use require --download --yes. JSON emits the complete preflight plan on stderr before requests and includes it in the final stdout object. Skip/test/defer/cloud paths need no acknowledgement, and no legal attestation is persisted. Automatic Linux llama.cpp acquisition remains disabled.

Example

mars setup
mars setup --inference local --local-bundle auto --download --yes --json

mars path setup

Adds the installed command directory to supported shell profile files. It is idempotent and supports Fish, Zsh, Bash, POSIX sh/Ksh, Csh, and Tcsh. The Shell Integration Reference covers profile targets, reload hints, stale command caches, and completions.

Flags

--install-dir, --shell, --dry-run, --json.

Example

mars path setup
mars path setup --install-dir /usr/local/bin --dry-run

mars auth github check, setup, and clear-local

check first makes one exact, no-redirect anonymous request to the official api.github.com release-metadata endpoint. Only an exact 401, 403, or 404 may resolve optional credentials and retry the same origin and path once. It reports anonymous, authenticated, or unavailable without disclosing credentials. setup can persist optional auth for private forks or rate-limit fallback. See the Authentication And Credentials Reference for how this differs from model provider credentials.

Flags

--config, --token on setup, --json.

Security

clear-local removes only the stored config github_token. It never changes environment variables, GitHub CLI or GitHub App credentials, repositories, or remote state.

Example

mars auth github check --json
mars auth github clear-local

mars update tool and mars update check

update check reports installed CLI and target harness drift. Source checkout make update-tool is the current supported reinstall path. Packaged update tool flags are reserved for a future approved F-018 signed release and historical raw assets are unsupported.

Check flags

--repo, --latest-release-url, --skip-remote, --json.

Tool flags

--version latest|vX.Y.Z|main, --install-dir, --source, --dry-run, --json.

Tool aliases

mars update binary and mars update cli run the same command as mars update tool.

Current supported example

mars update check --repo ~/my-project --json
make update-tool
mars version

mars init

Scaffolds a deployed harness into a git checkout. It writes .harness/, generated agent guidance, tickets, feature contracts, release files, model routing metadata, and docs that make the target usable by MARS, Codex, Cursor, and humans.

Flags

--repo, --force, --model-routing local|cloud|defer, --local-bundle, --cloud-provider, --cloud-model, --cloud-endpoint, --api-key-env, --yes, --json, --plain.

Example

mars init --repo ~/my-project
mars init --repo ~/my-project --model-routing cloud --cloud-provider openai --cloud-model gpt-4.1-mini --api-key-env OPENAI_API_KEY --yes --json

mars update harness and mars upgrade

Fills missing generated defaults for an existing target without overwriting user-owned manifest, role prompts, knowledge routes, guardrails, tickets, plans, references, or target AGENTS.md.

mars update harness --repo ~/my-project
mars upgrade --repo ~/my-project

Aliases: mars update target and mars update bundle.

mars scan

Scans a repository for gaps. With --tickets, it writes deduplicated backlog tickets through the canonical ticket lifecycle.

Flags

--repo, --tickets.

Example

mars scan --repo ~/my-project --tickets

mars eject

Removes MARS from a target repo. Dry-run is the default. Applying requires --apply --confirm <repo-name>. The command removes generated harness artifacts and the associated per-repo database, but it does not rewrite git history.

Flags

--repo, --db, --apply, --confirm, --keep-db, --delete-shared-db.

Aliases

mars uninstall and mars kill-switch.

Example

mars eject --repo ~/my-project
mars eject --repo ~/my-project --apply --confirm my-project

mars run <role>

Runs a single role against one repository. Use it for manual ticket work, targeted repair, role prompt debugging, and dry-run context inspection.

Flags

--repo, --model-endpoint, --trace, --debug, --log-file, --dry-run, --no-init, --code-intel, --budget, --max-turns, --execution-profile, --acknowledge-host-execution.

Safe inspection

Pair --dry-run --no-init when a target has no harness and you do not want files written.

Example

mars run engineer --repo ~/my-project --execution-profile host --acknowledge-host-execution
mars run qa --repo ~/my-project --debug --execution-profile host --acknowledge-host-execution
mars run engineer --repo ~/legacy-project --dry-run --no-init

mars start

The single-repo lifecycle path. Acknowledged-host mode initializes if needed, registers the repo, reconciles lifecycle state, starts the control/dashboard listeners, and runs the scoped pipeline with repo-isolated database state.

Flags

--repo, --concurrency, --db, --force, --new-lifecycle, --debug, --log-file, --code-intel, --model-endpoint, --addr, --dashboard-addr, --yes, --json, --plain, --execution-profile, --acknowledge-host-execution.

When to use --new-lifecycle

Only when you deliberately want a fresh CEO lifecycle over resumable work.

Example

mars start --repo ~/my-project --execution-profile host --acknowledge-host-execution
mars start --repo ~/my-project --model-endpoint http://127.0.0.1:8080/v1 --execution-profile host --acknowledge-host-execution

mars register and mars serve

The persistent multi-repo path. Register target repos, then run the orchestrator, dashboard, webhook receiver, scheduler, worker pool, recovery watchdog, and survey loop from serve.

Register flags

--repo, --remote, --branch, --db.

Serve flags

--addr, --concurrency, --db, --debug, --log-file, --code-intel, --execution-profile, --acknowledge-host-execution.

Example

mars register --repo ~/my-project --remote owner/repo
mars serve --addr 127.0.0.1:9091 --concurrency 2 --execution-profile host --acknowledge-host-execution

mars checks run

Runs the command after -- inside the target repo and records whether it passed or failed.

mars checks run --repo ~/my-project --name go-test -- go test ./...
mars checks run --repo ~/my-project --role qa --name npm-test -- npm test

Required

--repo and --name.

Default role

engineer, unless --role is set.

Failure behavior

A failed command is recorded as checks_failed, then the CLI exits non-zero.

Open the Local Checks Evidence Guide

mars models eligible and list

Shows local bundle eligibility and provider catalogs. Registry bundles are safe default candidates; Ollama listing is a broad evaluation/swap surface, not automatic default promotion.

mars models eligible --json
mars models list --provider registry
mars models list --provider ollama

mars models evaluate

Runs or plans benchmark probes for model candidates. Live reports include provider, model, endpoint, hardware profile, timing, token counts, failures, and promotion status.

Flags

--endpoint, --model, --provider, --api-key-env, --repo, --report-dir, --save-report, --revision, --sha256, --source, --cloud, --timeout, --json.

mars models override

Writes repo-owned model routing overrides to .harness/model-overrides.yaml. Role overrides take precedence over tier overrides, then the default registry route applies.

mars models override --repo ~/my-project --tier coding --provider ollama --model qwen3.6:27b
mars models override --repo ~/my-project --role engineer --provider openai-compatible --endpoint http://127.0.0.1:8088/v1 --model repo-coder

mars models credentials write-local-env

Copies a provider key from the current process environment into ignored .harness/.env.local with restricted file permissions. Committed config stores only api_key_env. See the Authentication And Credentials Reference.

export OPENAI_API_KEY=...
mars models credentials write-local-env --repo ~/my-project --api-key-env OPENAI_API_KEY --yes --json

mars release notes

Generates semantic-versioned patch notes from semantic commits, updates VERSION, prepends CHANGELOG.md, and in this source repo updates internal/buildinfo/version.go.

mars release notes --repo . --bump auto --dry-run
mars release notes --repo . --bump auto

mars release backfill-notes

Backfills historical release entries to current narrative standards. Use --check in gates and --dry-run before rewriting.

mars release backfill-notes --repo . --check
mars release backfill-notes --repo . --min-version 0.60.0 --max-version 0.68.0 --dry-run

Release artifact verification

mars release verify-assets and mars release audit were retired by T-066 D1 and are unknown commands. MARS source uses AD-315's conventional no-publish rehearsal contract and F-018 attested archive consumer; target repositories use their repository-owned producer and verifier. A Release listing, upload exit, asset names, or checksums alone is not authenticity or completion evidence, and missing or unverifiable state remains blocked.