The minga CLI

Applies to

Runner 0.6.1 · checked 11 October 2026. minga --version prints yours.

minga is the runner and its command-line tool, in one binary. Install it with curl -fsSL https://app.minga.run/install.sh | sh.

All commands

minga runner login   [--server <url>] [--name <name>] [--no-open]
minga runner logout
minga runner start   [--foreground]
minga runner stop
minga runner install [--print]
minga runner uninstall
minga status         [--json]
minga profile add    <claude|codex> --id <id> --home <dir> [--workspaces <ids>] [--default] [--cli-path <path>]
minga profile list
minga profile check  [<id>] [--json]
minga profile scope  <id> <workspaceId...> | <id> --all
minga profile set    <id> <key> <value>
minga profile cli    <id> [--claude-permission-mode <mode>] [--claude-sandbox <on|off|unset>]
                          [--codex-sandbox <mode>] [--codex-approval-policy <policy>]
minga repo add       <path>
minga repo list
minga repo remove    <path-or-remote>
minga update         [--check] [--version <v>] [--server <url>]

Every command takes --help (-h). minga --version (-v) prints the version, and minga --completions <bash|zsh|fish> prints a shell completion script.

minga runner

Pair, start and install this machine’s runner.

minga runner login

Pairs this machine with a Minga workspace, using a device code. It works over SSH: open the link on any device where you are signed in.

Flag	Default	Meaning
--server <url>	https://app.minga.run	The Minga server
--name <name>	the machine’s host name	The runner’s name in the app
--no-open	off	Don’t open the browser (macOS opens it otherwise)

minga runner login --name vps-1

It prints a link and a code, waits for your approval (up to 10 minutes), then saves the credentials to ~/.config/minga/credentials with mode 0600. A machine has one pairing: run minga runner logout first to pair it with another workspace. If a runner is already running, it reconnects with the new credentials.

minga runner logout

Removes this machine’s pairing: its credentials and pinned signing keys. The runner stays listed in the app until you remove it there.

minga runner logout

minga runner start

Starts the runner: it connects to Minga and serves the local control socket.

Flag	Default	Meaning
--foreground	off	Run in this terminal. This is what the service runs.

Without --foreground: if the service is installed, it starts the service; otherwise it starts the runner in the background and prints its process id and the log file.

minga runner start

minga runner stop

Stops the runner, and its LaunchAgent or systemd service if installed (until the next minga runner start or your next login). Waits up to 10 seconds.

minga runner stop

minga runner install

Installs the runner as a user service that starts at login and restarts if it stops: a LaunchAgent on macOS (~/Library/LaunchAgents/run.minga.runner.plist), a systemd --user unit on Linux (~/.config/systemd/user/minga-runner.service). The service gets the PATH of the shell you run it from.

Flag	Default	Meaning
--print	off	Only print the service file; install nothing

minga runner install

On Linux, run sudo loginctl enable-linger $USER (it prints this) to keep the runner up while you are logged out.

minga runner uninstall

Removes the runner service.

minga runner uninstall

minga status

Shows the local runner’s connection state, server, workspace, settings (capacity, auto-update), profiles and repos. When the runner is not running, it shows what runner.toml says and never changes the file.

Flag	Default	Meaning
--json	off	Print the status as JSON

minga status

minga profile

Manage CLI profiles: one per Claude Code or Codex setup (home directory) on this machine. Profiles are kept in runner.toml.

minga profile add

Registers an existing CLI setup as a profile. Adding an id that exists updates it and keeps its other settings.

Argument or flag	Default	Meaning
<claude|codex>	required	The CLI
--id <id>	required	The profile id: lowercase letters, digits and -, starting with a letter or digit, at most 40 characters
--home <dir>	required	The CLI’s home: CLAUDE_CONFIG_DIR for Claude Code, CODEX_HOME for Codex (~/.claude and ~/.codex are the defaults)
--workspaces <ids>	all	Comma-separated workspace ids this profile may serve
--default	off	Make it the default profile for its CLI
--cli-path <path>	from PATH	The CLI binary for this profile

minga profile add codex --id codex-work --home ~/.codex-work --default

If the home does not exist yet, it prints how to sign in there first.

minga profile list

Lists the profiles in runner.toml with their home, access mode, default mark and workspaces.

minga profile list

minga profile check

Checks profiles: whether the CLI is signed in, which models it offers, and its usage. It never reads the contents of your credentials and never runs a model turn.

Argument or flag	Default	Meaning
<id>	every profile	Check one profile
--json	off	Print the full report as JSON

minga profile check claude-personal

minga profile scope

Limits a profile to some workspaces, or with --all lets it serve every workspace again. Give workspace ids or --all, not both. A running runner picks the change up at once.

minga profile scope codex-work <workspaceId>
minga profile scope codex-work --all

minga profile set

Sets one profile setting. It prints the profile’s effective settings afterwards, and a running runner picks the change up at once.

Key	Values	Default	Meaning
access	auto, ask, full	auto	The access mode
mcp	cli, minga_only	cli	MCP servers a run loads: the CLI’s own plus Minga’s, or Minga’s only
mcp-approval	approve, ask	approve	In Auto: MCP tools run without asking, or ask when the CLI asks
network	on, off	on	Codex in Auto: network access in the sandbox
model	a model id, or default	the CLI’s default	The model for runs that name none
effort	low, medium, high, max, or default	the CLI’s default	The effort for runs that name none

minga profile set codex-personal access ask
minga profile set claude-personal model default

minga profile cli

Shows, or sets, a profile’s advanced CLI overrides. An override replaces what the access mode would pass; unset hands it back to the access mode. Without flags it only prints the effective values.

Flag	Values
--claude-permission-mode	default, acceptEdits, bypassPermissions, plan, dontAsk, auto, unset
--claude-sandbox	on, off, unset (unset passes nothing; your Claude Code settings decide)
--codex-sandbox	read-only, workspace-write, danger-full-access, unset
--codex-approval-policy	untrusted, on-request, never, unset

minga profile cli codex-work --codex-sandbox workspace-write
minga profile cli codex-work

A profile with an override shows its access mode as (custom).

minga repo

Register the local clones this runner works in. See Attach a repo.

minga repo add

Registers a local clone. The path must be a git repository with an origin remote. The runner checks its default branch, read access and push access, from the running service if there is one.

minga repo add ~/code/dictly

It warns when another registered clone already serves the same remote.

minga repo list

Lists registered clones (remote, whether the workspace uses them, default branch, read and push status) and the clones the runner found in your Claude Code and Codex sessions and its own worktrees.

minga repo list

minga repo remove

Unregisters a clone, by path or by remote. Worktrees are left as they are.

minga repo remove ~/code/dictly

minga update

Updates the minga binary to the latest signed release. It checks the SHA-256 sum and the Ed25519 signature before it replaces anything. A running runner restarts into the new version as soon as its active runs end and takes no new runs meanwhile.

Flag	Default	Meaning
--check	off	Only check whether a newer release exists
--version <v>	latest	Install this exact version (also a downgrade)
--server <url>	the paired server, else https://app.minga.run	The release server

minga update --check
minga update

A binary built from source does not update itself; use --check there.

Developer tools

minga debug turn

Not listed in minga --help. Runs one real turn through a profile’s CLI driver and prints the normalized events. It starts a model turn, so it uses your CLI’s model and quota.

Argument or flag	Default	Meaning
<profile>	required	The profile id
<prompt>	required	The prompt
--model <m>	haiku for Claude; the CLI’s default for Codex	The model
--cwd <dir>	a new temp directory	The working directory

minga debug turn claude-personal "Say hello"