Move a repo from plain git checkout to a MARS target.

Decision Map

Use this table to choose the right command before touching a target repo. For exact flags, use the CLI Reference or mars <command> --help.

Before You Touch A Repo

1. Confirm it is the target project

   The target project is the application, service, library, or docs repo MARS should manage. Do not point ordinary target agents at the MARS source repo.

2. Confirm git state

   git -C /path/to/repo status --short --branch

   The repo is the system of record. Generated harness files, tickets, docs, release state, and later agent commits are meant to be reviewed through git.

3. Pick the inspection level

   Use mars init when you want generated files. Use mars run <role> --dry-run --no-init when you need an observer-safe preview against an uninitialized repo.

4. Keep runtime artifacts out of the target repo

   Per-repo databases default to ~/.mars/db/{repo}/mars.db. Command logs and traces default under ~/.mars/traces/. Do not put runtime SQLite databases or trace logs inside the target worktree.

Initialize

mars init is the deliberate way to scaffold the deployed harness before running agents. It requires a git checkout and writes repo-owned files users should inspect and commit.

mars init --repo /path/to/repo
git -C /path/to/repo status --short
git -C /path/to/repo diff --stat

Automatic Scaffolding

register and scan use the same scaffold path as mars init when the manifest is missing. run and start use it only in acknowledged-host mode; observer rejects a missing target before writes apart from the explicit no-init dry-run preview.

Register

mars register records a local repo so the orchestrator can manage it. The default database is isolated per target at ~/.mars/db/{repo}/mars.db.

mars register --repo /path/to/repo --remote owner/repo --branch main
mars register --repo /path/to/repo --db /private/tmp/mars-demo.db

Start

Acknowledged-host mars start is the scoped one-repo autonomous loop. It initializes when needed, registers the repo, reconciles resumable lifecycle state, starts the dashboard and workers, and executes the delivery operating model.

mars start --repo /path/to/repo --execution-profile host --acknowledge-host-execution
mars start --repo /path/to/repo --concurrency 1 --execution-profile host --acknowledge-host-execution
mars start --repo /path/to/repo --debug --log-file /private/tmp/mars-start.log --execution-profile host --acknowledge-host-execution

All five agent entry points default to observer, which independently caps trust and blocks every target mutator. Host has the current OS user's full authority and is not containment; isolated is unavailable.

Open the Operations Guide for dashboard controls, pause/resume, restart, scan, stop, queue, and database recovery behavior.

Run One Role

mars run loads the target bundle and executes one role. Use it for deliberate single-role work, dry-run inspection, and debugging role context.

mars run engineer --repo /path/to/repo --dry-run

mars run engineer --repo /path/to/repo --dry-run --no-init

mars run engineer --repo /path/to/repo --max-turns 20 --budget 120000 --execution-profile host --acknowledge-host-execution

Scan

mars scan walks the repo for starter gaps such as TODOs, missing tests, missing CI, and large functions. With --tickets, it writes deduplicated backlog tickets under docs/tickets/backlog/.

mars scan --repo /path/to/repo
mars scan --repo /path/to/repo --tickets

Health And Drift

Use health and drift commands before asking an agent to fix something mysterious. They separate machine setup, local runtime, target harness, update, active-plan, and integration problems.

mars doctor --repo /path/to/repo
mars doctor --repo /path/to/repo --json

mars update check --repo /path/to/repo --json
mars update check --repo /path/to/repo --skip-remote

mars scores --repo /path/to/repo
mars scores export --repo /path/to/repo

Upgrade

mars upgrade fills missing target harness defaults after the installed tool changes. It preserves user-owned files such as manifest, role prompts, knowledge routes, guardrails, tickets, exec plans, design docs, references, and target AGENTS.md.

mars upgrade --repo /path/to/repo
mars update harness --repo /path/to/repo

Eject

mars eject is the repo-level kill switch. It is a dry run by default. Destructive removal requires both --apply and --confirm <repo-name>.

mars eject --repo /path/to/repo
mars eject --repo /path/to/repo --apply --confirm repo
mars eject --repo /path/to/repo --apply --confirm repo --keep-db

State Map

Recipes

mars init --repo /path/to/repo
git -C /path/to/repo status --short
git -C /path/to/repo diff -- .harness AGENTS.md docs VERSION CHANGELOG.md
git -C /path/to/repo add .harness AGENTS.md docs VERSION CHANGELOG.md .gitignore
git -C /path/to/repo commit -m "chore: initialize mars harness"

mars run engineer --repo /path/to/repo --dry-run
mars run engineer --repo /path/to/uninitialized-repo --dry-run --no-init

mars start --repo /path/to/repo --db ~/.mars/db/my-repo/mars.db --concurrency 1 --execution-profile host --acknowledge-host-execution

mars doctor --repo /path/to/repo --json
mars update check --repo /path/to/repo --json
mars upgrade --repo /path/to/repo

mars eject --repo /path/to/repo
mars eject --repo /path/to/repo --apply --confirm repo

Troubleshooting