CLI and Runtime

Desktop and CLI are complementary

The desktop app is the best operational surface for most people. The CLI remains useful when you want:

terminal-driven automation
direct scripting
lower-level debugging
to run in environments without the desktop shell

On supported packaged desktop builds, you do not need a separate CLI download just to get terminal access. The app can seed the bundled CLI into its app-data directory and expose it through a managed ~/.local/bin/maabarium shell link.

What the core runtime owns

The runtime logic in maabarium-core is responsible for:

engine orchestration
blueprint parsing
evaluator execution
Git dependency readiness and install guidance
git and worktree flow
persistence
logging and secrets handling

Example CLI exploration

cargo run -p maabarium-cli -- run blueprints/example.toml --db data/maabarium.db
cargo run -p maabarium-cli -- status --db data/maabarium.db

Those commands are most relevant for contributors and advanced operators.

CLI setup commands

The guided setup work is also exposed through the CLI when you want an inspectable readiness pass without opening the desktop shell.

cargo run -p maabarium-cli -- setup --check
cargo run -p maabarium-cli -- setup --check --json

Use these commands when you want to:

inspect Git readiness and installability
confirm provider and local-runtime prerequisites before a real run
integrate setup checks into local scripts or automation
capture machine-readable readiness output with --json

The desktop app remains the best interactive surface, but the CLI setup path gives contributors and automation-heavy operators the same readiness model in terminal form.

CLI self-update commands

If you are using a packaged or seeded CLI install rather than cargo run, the CLI can also inspect and apply its own published updates.

maabarium self version
maabarium self check
maabarium self update

Those commands use the same release metadata story as the desktop updater flow. self version shows the configured channel and manifest, self check reports whether a newer CLI archive is available for your platform, and self update installs that archive in place.

What a CLI run does now

Before a workflow starts, the CLI checks whether Git is available. If Git is missing, Maabarium reports that directly and attempts automatic installation through a supported system installer when possible.

After a run finishes, the CLI prints an aggregated timing summary. That summary rolls up phase totals, average iteration duration, and proposal-failure counters so you can inspect run cost without manually combining log lines.

For portable optimised local binaries and deeper runtime details, continue into Build Profiles and Runtime Behaviour.

When to prefer desktop

Prefer the desktop path when you want faster visibility and lower cognitive load while still keeping access to logs, telemetry, workflow selection, and persisted history.

The desktop setup flow is also the simplest way to manage the optional shell link:

Install CLI Link creates or refreshes the managed symlink
Remove CLI Link removes only that shell link
the app warns if ~/.local/bin is not exported in your shell PATH

The desktop setup modal also keeps Guided and Advanced operator paths in one place, including environment profiles, remote-provider validation, workspace auto-detection, and the in-context Run Setup re-entry path from Maintenance.

Removing the .app bundle does not remove the shell link automatically, because that integration lives outside the app bundle.