# Skill: CLI

The Mimic CLI (`@mimicprotocol/cli`) is the main tool for scaffolding, building, and deploying functions. You use it via `npx` without a global install, or as a local dev dependency invoked through `yarn mimic`.

## Recommended Agent Workflow

When an AI agent helps with Mimic projects, follow these defaults:

1. Always verify the CLI version first and prefer the latest release.
2. For new projects, always start with `init` instead of creating files manually.

### 1) Always use the latest CLI

Use the latest CLI when running ad-hoc commands:

```bash
npx @mimicprotocol/cli@latest <command>
```

If the project uses a local dev dependency, check and update it before continuing:

```bash
yarn mimic --version
npm view @mimicprotocol/cli version
yarn add -D @mimicprotocol/cli@latest
```

This avoids version drift across workspaces and prevents docs/code mismatches.

### 2) Start new projects with `init`

For new function projects, bootstrap with `init` first, even when working in multi-workspace setups:

```bash
npx @mimicprotocol/cli@latest init [directory]
```

`init` creates the correct baseline (`manifest.yaml`, TypeScript setup, starter function, dependencies, and codegen). Manual scaffolding should be the exception, not the default.

***

## Installation

No global install required. Run any command directly with `npx`:

```bash
npx @mimicprotocol/cli@latest <command>
```

Or add it as a local dev dependency and invoke it through yarn scripts:

```bash
yarn add -D @mimicprotocol/cli@latest
yarn mimic <command>
```

***

## Commands

### `init` — Scaffold a new project

Creates a minimal project structure with a manifest file, a starter function, and all dependencies.

```bash
npx @mimicprotocol/cli@latest init [directory] [--force]
```

| Option        | Description                                      | Default |
| ------------- | ------------------------------------------------ | ------- |
| `directory`   | Where to initialize the project                  | `./`    |
| `--force, -f` | Overwrite existing files (asks for confirmation) | `false` |

**Examples**

```bash
# New project in ./my-function
npx @mimicprotocol/cli@latest init ./my-function

# Reinitialize in an existing directory
npx @mimicprotocol/cli@latest init ./my-function --force
```

**Output structure**

```
my-function/
├── manifest.yaml      # Function metadata, inputs, and ABI references
├── package.json
├── tsconfig.json
└── src/
    └── function.ts    # Your AssemblyScript function
```

After scaffolding, the CLI automatically runs `yarn install` and `yarn codegen`.

***

### `codegen` — Generate types from the manifest

Reads `manifest.yaml` and generates typed AssemblyScript interfaces for declared inputs and ABIs into `src/types/`.

```bash
yarn mimic codegen [--manifest <path>] [--output <dir>] [--clean]
```

| Option           | Description                                                   | Default         |
| ---------------- | ------------------------------------------------------------- | --------------- |
| `--manifest, -m` | Path to manifest file                                         | `manifest.yaml` |
| `--output, -o`   | Output directory for generated types                          | `./src/types`   |
| `--clean, -c`    | Delete existing types before regenerating (asks confirmation) | `false`         |

**Examples**

```bash
yarn mimic codegen
yarn mimic codegen --manifest ./custom-manifest.yaml --output ./src/generated
yarn mimic codegen --clean
```

**Output**

* `src/types/index.ts` — Input parameter types
* `src/types/<ContractName>.ts` — One file per ABI, with read/write methods and event decoders

{% hint style="info" %}
Run `codegen` every time you change `manifest.yaml`. Generated files are meant to be committed — do not edit them manually.
{% endhint %}

***

### `compile` — Build to WebAssembly

Validates the manifest and compiles your AssemblyScript function into a WASM binary.

```bash
yarn mimic compile [--function <path>] [--manifest <path>] [--output <dir>]
```

| Option           | Description           | Default           |
| ---------------- | --------------------- | ----------------- |
| `--function, -f` | Path to entry file    | `src/function.ts` |
| `--manifest, -m` | Path to manifest file | `manifest.yaml`   |
| `--output, -o`   | Output directory      | `build`           |

**Examples**

```bash
yarn mimic compile
yarn mimic compile --function ./functions/myFunction.ts --output ./out
```

**Output**

```
build/
├── function.wasm     # Compiled WebAssembly binary
└── manifest.json     # Validated manifest
```

***

### `login` — Save your API key locally

Stores credentials in `~/.mimic/credentials` so you don't need to pass `--api-key` on every deploy.

```bash
mimic login [--profile <name>] [--api-key <key>] [--force-login]
```

| Option              | Description                                     | Default   |
| ------------------- | ----------------------------------------------- | --------- |
| `--profile, -p`     | Profile name                                    | `default` |
| `--api-key, -k`     | API key (skips interactive prompt)              | —         |
| `--force-login, -f` | Overwrite existing profile without confirmation | `false`   |

**Examples**

```bash
mimic login                                              # interactive
mimic login --profile staging --api-key YOUR_API_KEY    # non-interactive
```

{% hint style="info" %}
Retrieve your API key from the [Mimic explorer](https://protocol.mimic.fi/) under account settings. Profile names cannot contain `[`, `]`, or `=`.
{% endhint %}

***

### `logout` — Remove stored credentials

```bash
mimic logout [--profile <name>] [--force]
```

```bash
mimic logout                    # removes default profile, asks confirmation
mimic logout --profile staging
mimic logout --force            # skips confirmation
```

***

### `profiles` — List configured profiles

```bash
mimic profiles
```

```
Configured profiles (stored in ~/.mimic/credentials):

* default (default)
* staging
* production

Use mimic deploy --profile <name> to deploy with a specific profile.
```

***

### `deploy` — Upload to the Mimic Registry

Runs codegen + compile (unless skipped), uploads artifacts to IPFS, and registers the function in the Mimic Registry so relayers can discover it.

```bash
yarn mimic deploy [options]
```

| Option           | Description                       | Default                         |
| ---------------- | --------------------------------- | ------------------------------- |
| `--api-key, -k`  | API key                           | —                               |
| `--profile, -p`  | Credential profile to use         | `default`                       |
| `--input, -i`    | Directory with compiled artifacts | `build`                         |
| `--output, -o`   | Directory to write the CID file   | `build`                         |
| `--skip-compile` | Skip codegen and compile          | `false`                         |
| `--url, -u`      | Registry base URL                 | `https://api-protocol.mimic.fi` |

**Examples**

```bash
yarn mimic deploy                               # uses default profile
yarn mimic deploy --api-key my-key
yarn mimic deploy --profile production
yarn mimic deploy --input ./dist --skip-compile
```

**Before uploading**, the CLI validates that `build/` contains both `manifest.json` and `function.wasm`.

**Output**: `build/CID.json` — the IPFS Content Identifier for your deployed function.

***

### `test` — Run function tests

Runs `codegen` + `compile`, then executes `tests/**/*.spec.ts` with Mocha.

```bash
yarn mimic test [--directory <path>] [--skip-compile]
```

| Option            | Description                           | Default |
| ----------------- | ------------------------------------- | ------- |
| `--directory, -d` | Function directory to test            | `./`    |
| `--skip-compile`  | Skip codegen and compile before tests | `false` |

```bash
yarn mimic test
yarn mimic test --skip-compile    # if artifacts are already up to date
```

***

## Multi-function projects (`mimic.yaml`)

For projects with more than one function, create a `mimic.yaml` at the project root. All commands (`codegen`, `compile`, `test`, `deploy`) will iterate over every function defined in it.

```yaml
functions:
  - name: function-one
    manifest: ./function-one/manifest.yaml
    function: ./function-one/src/function.ts
    build-directory: ./function-one/build
    types-directory: ./function-one/src/types

  - name: function-two
    manifest: ./function-two/manifest.yaml
    function: ./function-two/src/function.ts
    build-directory: ./function-two/build
    types-directory: ./function-two/src/types
```

**Filtering**

```bash
# Only run for specific functions
yarn mimic compile --include function-one function-two

# Run for all except one
yarn mimic codegen --exclude function-two

# Override the config file location
yarn mimic compile --config-file ./config/functions.yaml

# Ignore mimic.yaml entirely
yarn mimic compile --no-config --function ./src/function.ts
```

{% hint style="info" %}
`mimic.yaml` is optional — single-function projects can continue using individual command flags without it.
{% endhint %}