# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mimic.fi/skills/skill-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.