Metadata-Version: 2.4
Name: mirrorneuron-cli
Version: 1.2.31
Summary: MirrorNeuron CLI
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mirrorneuron-python-sdk
Requires-Dist: jsonschema>=4.25
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: web-ui
Requires-Dist: mirrorneuron-web-ui-skill; extra == "web-ui"
Dynamic: license-file

# MirrorNeuron CLI

`mn-cli` provides the `mn` command for validating and running blueprints,
inspecting runtime state, managing jobs, exporting artifacts, and starting local
services installed by `mn-deploy`.

## Air-gapped jobs

Blueprints may bundle source packages or wheels under `payloads/skills` and
`payloads/agents`, and Docker Model Runner sources under `payloads/models`.
Large model files are streamed into the local blob store.

For a paused job, `mn job backup <id> --air-gapped --output <folder>` writes an
`mn.backup.v2` capsule containing the runtime snapshot, payload blobs, Python
wheelhouse, and required DockerWorker images. `mn job restore` hydrates those
assets without package-index access. An extracted capsule can also be run by
passing its `bundle` directory to `mn blueprint run --folder`. Every runtime
model must have a physical `payloads/models` source; export fails instead of
silently depending on a catalog download.

## Quick Start

Install locally and run tests:

```bash
python3.11 -m venv .venv
. .venv/bin/activate
.venv/bin/python -m pip install -e .
.venv/bin/python -m pytest -q
```

Try the CLI:

```bash
mn --version
mn node list
mn blueprint run message_routing_trace
```

Static HTML exports use the optional `mirrorneuron-web-ui-skill` package. With
the MirrorNeuron GAR package index configured, install it with:

```bash
.venv/bin/python -m pip install "mirrorneuron-cli[web-ui]"
```

## Fast runtime-model orchestration tests

Model-aware blueprint launch logic is testable without Core, Docker, DMR,
LiteLLM, SSH, or a network. `RuntimeModelDependencies` supplies the model
catalog, resource report, system summary, `BlueprintModelOps`, and gateway
effects used by the real `run_bundle` handler. The reusable
`tests/runtime_model_fakes.py` cluster records model preparation, remote-route
reconciliation, and LiteLLM synchronization in memory.

Run the focused gate from this workspace:

```bash
../mn-system-tests/.venv/bin/python -m pytest -q \
  tests/test_run_cmds_models.py tests/test_run_cmds_run.py \
  -k "adaptive_model_placement or injected_remote_installed_state or injected_cluster"
```

The runtime-selection scenarios are:

- a local-only 16 GB Apple node validates the portable Gemma fallback policy;
- adding a healthy 128 GB CUDA node validates that Nemotron is feasible;
- already-installed remote models remain usable without a second install;
- the first SDK model call selects and prepares the owner node, then uses that
  node's reachable LiteLLM gateway route.

`mn blueprint run --debug` prints the deferred policy for blueprint-declared
foundational LLMs. RAG and OCR model details are owned by their skills and
appear only in runtime events when those skills first call the SDK wrapper.
Those events report the selected model/node, fallback reason, and install/reuse state. Debug mode
also prints DockerWorker build commands and complete captured build output,
including builds performed through a remote node's native SDK service.

Live Spark checks are a separate, opt-in boundary smoke after this injected
gate passes; they are not the development loop for placement policy.

CPU-only HostLocal workflows stay on the submitting runtime node by default.
Detached runs keep their output relay alive until terminal state unless
`MN_RUN_EVENT_RELAY_MAX_SECONDS` is explicitly set.

Override blueprint config for one run without changing `config/overwrite.json`:

```bash
mn blueprint run --folder ./vc_assistant \
  --set document_sources.folder_path=/path/to/documents \
  --set execution.debug=true
```

Repeat `--set` for multiple values. Values use JSON types when possible and
otherwise remain strings.

For a blueprint-owned web service, override the listener without editing its
checked-in config:

```bash
mn blueprint run --folder ./cctv_operator --web-ui \
  --web-ui-host 0.0.0.0 \
  --web-ui-port 61017
```

`--web-ui-host` and `--web-ui-port` set `web_ui.service.host` and
`web_ui.service.port` for that run. A wildcard host exposes the service to
reachable peers; the blueprint is responsible for its authentication and
network-safety contract.

## Stable jobs and execution runs

Create a reusable job once, then start independent runs that share its declared
job data:

```bash
mn job create ./vc_assistant --job-id vc-diligence
mn job inspect vc-diligence
mn job start vc-diligence --inputs run-input.json
mn job runs vc-diligence

mn run status <run-id>
mn run pause <run-id>
mn run resume <run-id>
mn run cancel <run-id>
```

`job_id` is the stable configuration and data owner. `run_id` is one
execution and the identity used for control, logs, output, retention, and run
deletion. Starting the same job again creates another run; retrying a run does
not. Use `mn blueprint run --job-id <job-id>` to run an existing definition.
Without that option, blueprint run creates an ephemeral stable job and starts
its first run.
With `--job-id`, the CLI prepares the currently installed blueprint revision
and atomically replaces the inactive job's executable bundle before starting
the run. Job data, schedules, and earlier run history are preserved. In
contrast, `mn job start` and scheduled dispatches are source independent and
reuse the stored definition-scoped submission and Docker services.

Lifecycle commands are deliberately separate:

```bash
mn job archive vc-diligence            # retains shared data
mn job reset-data vc-diligence         # confirms; clears/reseeds and advances generation
mn run delete <terminal-run-id>         # confirms; never deletes shared data
mn job delete vc-diligence              # confirms; deletes all runs, runtime resources, definition, and data
```

The legacy `mn job status/pause/resume/cancel <old-job-id>` commands remain
execution-oriented v1 compatibility commands. Prefer `mn run ...` for v2.

## Durable bulk operations

`mn job cancel-all`, `mn job clear`, `mn node reconcile`, and `mn node drain`
start a durable Core operation and render item updates in completion order.
`MN_CLI_OUTPUT=plain` emits stable `→`, `✓`, and `! Warning:` progress lines;
the rich terminal shows live counters and recent results.

If the owner of a cancelled job is offline, `cancellation_pending` means the
request was accepted and cleanup is queued for that node's rejoin. It is not a
command failure. Ctrl+C detaches without aborting the operation; reattach with:

```bash
mn operation status op-…
mn operation watch op-…
```

`mn job clear` is destructive and requires confirmation unless `--yes` is
provided. Each terminal job is reported as cleared only after its owned runtime
processes, sandboxes, checkpoints, services, staged storage, artifacts, leases,
delivery state, and local prepared resources have been removed.

## Configuration

Configuration is loaded by `mn_cli.config`. `.env` files provide defaults, and
real environment variables always override them. `MN_ENV` selects the
environment-specific defaults file and defaults to `dev` when unset.

Precedence:

```text
real environment variables
> .env.${MN_ENV}
> .env
> built-in safe defaults
```

Development:

```bash
export MN_ENV=dev
cp .env.example .env.dev
mn --version
```

Tests:

```bash
export MN_ENV=test
mn --version
```

Production does not require any `.env` file. Provide deployment-specific values
through the real environment:

```bash
export MN_ENV=production
export MN_HOME=/var/lib/mirrorneuron
export MN_LOG_LEVEL=info
export MN_API_HOST=0.0.0.0
export MN_API_PORT=8080
mn runtime status
```

Keep secrets, credentials, production hostnames, production database URLs, cloud
credentials, and user-specific local paths out of source files. Use
environment variables or uncommitted `.env` files instead.

## Details

- [MirrorNeuron Component Guide](../mn-docs/component-guide.md#cli)
- [CLI Reference](../mn-docs/cli.md)
- [Environment Variables](../mn-docs/env_variables.md)
- [Monitor Guide](../mn-docs/monitor.md)

## Release Updates

`mn runtime update` and the periodic interactive update check use the newest
stable `install_support/v*` snapshot in `MirrorNeuronLab/mn-deploy` as their
release plan. The snapshot pins the Core release tag, the SDK/CLI/API Python
package versions, and the Web UI npm version. The updater installs the exact
Python package versions from the public GAR `agent-skills` index and configures
the exact Web UI npm version for Docker Compose; it does not follow a source
branch, package-manager `latest` tag, or the Core repository's latest-release
endpoint.

The Core remains a versioned GitHub Release binary because it is not a Python
or npm package. Its release asset URL is constructed from the same support
snapshot tag. For private mirrors, set `MN_DEPLOY_REPO`, `MN_DEPLOY_REF`,
`MN_PIP_INDEX_URL`, or `MN_PIP_EXTRA_INDEX_URL` before running the command.

## Notes

- A running MirrorNeuron core is required for live runtime commands.
- The default gRPC target comes from `MN_GRPC_TARGET`, then local deployment
  settings, then `localhost:55051`.
- Use `mn blueprint validate` before `mn blueprint run --folder` when checking a local bundle.
- Validation honors first-use runtime-model installation, so a compatible
  declared model need not already be installed.
- `mn blueprint run` validates model declarations but does not install models.
  Workers select, install, and route each managed model on its first actual use.
- Docker workers receive a worker-reachable model-control target and use the
  SDK to select the best cluster node independently for LLM and for model
  specifications supplied at runtime by RAG and OCR skills.
- Node-local workflows are hard-pinned as a whole after topology lowering.
  Runtime health rejects nodes whose coordination-store identity differs from
  the submitting Core or whose Redis endpoint is read-only.
- OpenShell workers that reuse a job-scoped sandbox are prepared before
  submission; the submitted node receives the concrete sandbox name and SSH
  host instead of asking Core to create host resources.
- `default` is a LiteLLM model group, not a concrete model: it prefers
  `nemotron3` and falls back to `gemma4:e2b` when no healthy node can run
  Nemotron. The existing cluster model monitor
  rebuilds these routes as nodes join, rejoin, or leave; incomplete peer
  snapshots retain the last safe routes until departure is confirmed.
  Gateway route names and `fallback_model` are read from the SDK's merged model
  catalog, including `~/.mn/models/catalog.json` (or `$MN_HOME`) and the
  highest-priority `MN_MODEL_CATALOG_PATH` override.
- `--debug` retains complete Docker build diagnostics and prints deferred model
  policies. Actual model/node selection appears later in runtime events.
