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 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

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