Metadata-Version: 2.4
Name: mirrorneuron-cli
Version: 1.1.0
Summary: MirrorNeuron CLI
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mirrorneuron-python-sdk
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# MirrorNeuron CLI

Command-line interface for operating a local MirrorNeuron installation.

The CLI submits workflow bundles, monitors jobs, manages the local runtime services, and runs blueprint workflows through a shared command surface.

## Features

- Submit, inspect, pause, resume, cancel, and clear runtime jobs.
- Stream job events and inspect dead-letter records.
- Start and stop the local MirrorNeuron components.
- Run blueprint catalog entries or local blueprint folders.
- Export blueprint run artifacts as Markdown or static HTML.
- Check for released package updates and install them after user confirmation.

## Tech Stack

| Area | Tooling |
| --- | --- |
| Runtime | Python 3.9+ |
| CLI framework | Typer |
| Terminal rendering | Rich |
| Core client | `mirrorneuron-python-sdk` |
| Packaging | setuptools with setuptools-scm |

## Prerequisites

- Python 3.9 or newer.
- A MirrorNeuron core reachable over gRPC.
- Docker for the default local core and Redis workflow.
- Optional: the released-package installer from `mn-deploy`, which installs and wires the CLI automatically.

## Installation

The released-package installer installs this package and exposes `mn` on your `PATH`.

Standalone install:

```bash
pip install mirrorneuron-cli
```

Developer install:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Configuration

| Variable | Default | Description |
| --- | --- | --- |
| `MN_GRPC_TARGET` | `localhost:50051` | Core gRPC target. |
| `MN_CORE_GRPC_TARGET` | unset | Fallback core gRPC target. |
| `MN_GRPC_TIMEOUT_SECONDS` | `10` | RPC timeout. Use `0` or `none` to disable. |
| `MN_GRPC_AUTH_TOKEN` | unset | Optional bearer metadata for protected gateways. |
| `MN_CLI_LOG_PATH` | `~/.mn/logs/cli.log` | CLI log file path. |
| `MN_CLI_OUTPUT` | `rich` | Set to `plain` to disable Rich formatting. |
| `MN_DISABLE_UPDATE_CHECK` | unset | Set to `1`, `true`, or `yes` to disable automatic update checks. |
| `MN_UPDATE_CHECK_INTERVAL_SECONDS` | `86400` | Minimum time between automatic update checks. |
| `MN_CORE_REPO` | `MirrorNeuronLab/MirrorNeuron` | GitHub repository used for core release update checks. |

## Usage

Check the runtime:

```bash
mn nodes
mn metrics
```

Submit and inspect a workflow:

```bash
mn validate ./bundle
mn run ./bundle
mn list
mn status <job_id>
mn monitor <job_id>
```

Manage jobs:

```bash
mn pause <job_id>
mn resume <job_id>
mn cancel <job_id>
mn dead-letters <job_id>
mn clear
```

Manage local services:

```bash
mn start
mn stop
```

## Blueprint Commands

Blueprint commands are grouped under `mn blueprint`.

```bash
mn blueprint list
mn blueprint install
mn blueprint update
mn blueprint run <blueprint_id>
mn blueprint run ./path/to/bundle_or_source_blueprint
mn blueprint run <blueprint_id> --offline
mn blueprint run <blueprint_id> --revision <git_sha_or_tag>
mn blueprint monitor --follow
mn blueprint tail <run_id>
mn blueprint compare <run_a> <run_b>
mn blueprint export <run_id> --format markdown
mn blueprint export <run_id> --format html
```

`mn blueprint run` accepts either an installed blueprint ID or a local folder. If the folder is already a bundle, the CLI submits it directly. If the folder is a Python source blueprint, the CLI generates a bundle under:

```text
~/.mn/generated_blueprint_bundles/<run_id>/
```

Catalog runs use the cached blueprint library by default. Run `mn blueprint update` or pass `--update` when you want to refresh the local cache.

Blueprint run artifacts are stored under:

```text
~/.mn/runs/<run_id>/
```

Use `--runs-root <path>` with `monitor`, `tail`, `compare`, or `export` to inspect a custom run directory.

## Updates

The CLI checks for released package updates in interactive terminals. When an update is available, it asks for confirmation before making changes.

Updating stops all MirrorNeuron components and running jobs. Update only when no important jobs are running. Backward compatibility is not guaranteed between releases.

Manual update commands:

```bash
mn update --check-only
mn update
mn update --yes
```

The updater checks:

- PyPI packages: SDK, blueprint support skill, CLI, and API.
- npm package: Web UI, when installed.
- GitHub Releases: MirrorNeuron core OTP tarball.

## Testing

```bash
python3 -m pytest -q
```

## Deployment

For normal local installs, use `mn-deploy/install_new.sh`. It installs the CLI from PyPI, the Web UI from npm, and the core from GitHub Release OTP tarballs.

For custom deployments, install `mirrorneuron-cli` into a managed virtual environment and set `MN_GRPC_TARGET` to the runtime gateway.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `mn` is not found | Ensure `~/.local/bin` is on `PATH`. |
| Runtime commands fail | Confirm the core is running and `MN_GRPC_TARGET` is correct. |
| Output contains terminal control codes | Set `MN_CLI_OUTPUT=plain`. |
| Update prompt is unwanted | Set `MN_DISABLE_UPDATE_CHECK=1`. |
| Web UI is not started by `mn start` | Confirm the Web UI was installed by the released-package installer. |

## Contributing

Keep command names stable and add tests for new commands, flags, and error paths. Prefer shared SDK methods over direct protocol handling.

## License

MIT.
