> ## 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](/deployment/offline-deployment) and [Offline Operations](/enterprise/offline-operations).