> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# EMEP CLI Specification

> emep CLI commands for model registration, compatibility checks, merge execution, experiments, evolution, evaluation, artifacts, deployment, and offline packaging.

The `emep` CLI is the primary command-line interface for EMEP. It wraps the REST API and adds local file operations, offline packaging, and batch workflows. Every command returns structured JSON on stdout and human-readable logs on stderr.

## Command Table

| Command | Arguments | Description |
| - | - | - |
| `emep model register` | `--source path`, `--format format`, `--config path`, `--id id` | Register a model from local or remote source into ModelRegistry. |
| `emep compat check` | `--model-a id`, `--model-b id`, `--strategy strategy` | Run ModelCompatibilityAnalyzer and output compatibility state. |
| `emep merge run` | `--models ids`, `--strategy strategy`, `--params json`, `--output-id id` | Execute a merge job via MergeEngine. Returns job ID for polling. |
| `emep experiment create` | `--type type`, `--config path`, `--dataset-refs ids` | Create an experiment record in ExperimentTracker. |
| `emep evolve start` | `--config path`, `--population-size n`, `--objectives list` | Start an evolution run via EvolutionEngine. |
| `emep eval run` | `--candidate-id id`, `--benchmarks ids`, `--backend backend` | Run candidate evaluation via EvaluationEngine. |
| `emep artifact fetch` | `--artifact-id id`, `--output path` | Download an artifact from ArtifactStore to local path. |
| `emep deploy promote` | `--model-id id`, `--stage stage`, `--reason text` | Promote a model to DEPLOYED status via DeploymentManager. |
| `emep offline pack` | `--model-id id`, `--output path`, `--include-deps` | Package a model, its dependencies, and inference config for offline deployment. |

## Global Flags

All commands support these flags:

| Flag | Description | | |
| - | - | - | - |
| `--api-key key` | API key for authentication. Overrides EMEP\_API\_KEY env var. | | |
| `--endpoint url` | EMEP API base URL. Defaults to [https://api.emep.dev](https://api.emep.dev). | | |
| \`--format json | yaml | table\` | Output format. Default is json. |
| `--verbose` | Include debug-level logs on stderr. | | |
| `--timeout seconds` | Request timeout. Default is 300. | | |

## CLI Execution Flowchart

```mermaid theme={null}
flowchart TD
    START(["START"]) --> PARSE["Parse command + flags"]
    PARSE --> VALIDATE["Validate arguments"]
    VALIDATE --> AUTH["Resolve API key"]
    AUTH --> DISPATCH["Dispatch to handler"]
    DISPATCH --> LOCAL{"Local or Remote?"}
    LOCAL -->|"Local"| LOCAL_OP["Local file operation"]
    LOCAL -->|"Remote"| API["Call REST API"]
    API --> POLL{"Async job?"}
    POLL -->|"Yes"| POLL_LOOP["Poll status loop"]
    POLL -->|"No"| FORMAT["Format response"]
    POLL_LOOP -->|"Running"| POLL_LOOP
    POLL_LOOP -->|"Done"| FORMAT
    LOCAL_OP --> FORMAT
    FORMAT --> OUTPUT["Write to stdout"]
    OUTPUT --> END(["END"])
```

## Example: Register and Merge

```bash theme={null}
# Register two models
emep model register --source ./model-a --format safetensors --id model-a
emep model register --source ./model-b --format safetensors --id model-b

# Check compatibility
emep compat check --model-a model-a --model-b model-b --strategy slerp

# Run merge
emep merge run --models model-a,model-b --strategy slerp --params '{"t": 0.5}' --output-id merged-ab

# Poll until complete
emep experiment get --id <job_id>
```

## Exit Codes

| Code | Meaning |
| - | - |
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication failure |
| 4 | API error (4xx/5xx) |
| 5 | Timeout |
| 6 | Local file error |

## Integration Points

* **REST API**: all remote commands map 1:1 to API endpoints.
* **ModelRegistry**: `model register` and `compat check` interact directly.
* **ArtifactStore**: `artifact fetch` downloads binaries.
* **DeploymentManager**: `deploy promote` triggers promotion workflows.
* **Offline Operations**: `offline pack` produces self-contained packages for air-gapped environments. See [Offline Deployment](https://doc.blueapi.ir/deployment/offline-deployment.md) and [Offline Operations](https://doc.blueapi.ir/enterprise/offline-operations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.