# CLI

The Mimic Protocol CLI is a command-line tool for building, managing, and deploying automated blockchain functions. Mimic Protocol is a blockchain automation protocol that allows developers to create programmable functions that execute automatically based on predefined conditions.

### 1. Initialize

Initializes a new Mimic-compatible project structure in the current directory. This command will create a minimal folder layout, a manifest file, and example AssemblyScript function.

#### 1.1. Usage

```bash
mimic init [directory] [options]
```

#### 1.2. Options

| Option        | Description                                                        | Default |
| ------------- | ------------------------------------------------------------------ | ------- |
| `directory`   | Directory to initialize project                                    | `./`    |
| `--force, -f` | Overwrite existing files if they already exist (asks confirmation) | `false` |

#### 1.3. Examples

```bash
# Initialize a fresh project using default settings
yarn mimic init

# Initialize in a specific directory
yarn mimic init ./my-function

# Force initialization, overwriting existing files (will ask for confirmation)
yarn mimic init ./my-function --force
```

#### 1.4. Output

```
my-function/
├── manifest.yaml      # Function configuration
├── package.json       # Node.js dependencies
├── tsconfig.json      # TypeScript configuration
└── src/
    └── function.ts        # Main function implementation
```

When `--force` is used in a non-empty directory, the CLI asks for confirmation before deleting contents.

After scaffolding, the CLI runs `yarn install` and then `yarn codegen` inside the initialized directory to set up dependencies and generate types.

The manifest describes metadata, inputs, and ABIs for your AssemblyScript function, so the CLI can validate, generate code, compile, and ultimately deploy your function. For example:

```yaml
version: 1.0.0
name: Balance Monitoring Function
description: Monitors an account's token balance and creates a swap intent if conditions are met.
inputs:
  - chainId: uint32
  - account: address
  - tokenIn: address
  - tokenOut: address
  - slippage: uint32
  - threshold: uint32
abis:
  - ERC20: "./abis/IERC20.json"
```

***

### 2. Codegen

Scans your `manifest.yaml` and generates typed interfaces for declared inputs and ABIs. This step is typically used to create or update TypeScript/AssemblyScript types for your project so you can safely reference them in your code.

#### 2.1. Usage

```bash
mimic codegen [options]
```

#### 2.2. Options

| Option                  | Description                                                                     | Default         |
| ----------------------- | ------------------------------------------------------------------------------- | --------------- |
| `--manifest, -m <path>` | Specify a custom manifest file path                                             | `manifest.yaml` |
| `--output, -o <dir>`    | Output directory for generated types                                            | `./src/types`   |
| `--clean, -c`           | Remove existing generated types before generating new files (asks confirmation) | `false`         |

#### 2.3. Examples

```bash
# Generate types in the default "src/types" directory
yarn mimic codegen

# Generate types from a custom manifest, output to a "generated" folder
yarn mimic codegen --manifest ./custom-manifest.yaml --output ./src/generated

# Clean previous outputs (will ask confirmation) and regenerate
yarn mimic codegen --clean
```

#### 2.4. Output

* `./src/types/index.ts` - Input parameter types
* `./src/types/[ContractName].ts` - Contract interface types (one per ABI)

{% hint style="info" %}
For details about how ABI wrappers are generated and how to use them (read/write functions, tuples, arrays, and events), see the [ABI wrappers guide](broken://pages/dk2qcGLGN3Lk3CdCqpVL).
{% endhint %}

***

### 3. Compile

Compiles your AssemblyScript function into a Wasm binary, along with validating your manifest and producing any required runtime artifacts (like `manifest.json`). This step ensures you have a complete, ready-to-deploy package of your function logic and metadata.

#### 3.1. Usage

```bash
mimic compile [options]
```

#### 3.2. Options

| Option                     | Description                             | Default           |
| -------------------------- | --------------------------------------- | ----------------- |
| `--function, -f <path>`    | Path to the AssemblyScript entry file   | `src/function.ts` |
| `--manifest, -m <path>`    | Path to the manifest file to validate   | `manifest.yaml`   |
| `--output, -o <directory>` | Output directory for compiled artifacts | `build`           |

#### 3.3. Examples

```bash
# Compile using the default function and manifest
yarn mimic compile

# Compile a specific file, output to a custom directory
yarn mimic compile --function ./functions/myFunction.ts --output ./out
```

#### 3.4. Outputs

* `build/function.wasm` - Compiled WebAssembly binary
* `build/manifest.json` - Processed manifest configuration

The CLI validates the manifest before compiling. If the compilation fails, it reports an error and suggestions.

***

### 4. Login

Authenticates with Mimic by storing your API key locally. This allows you to deploy functions without having to provide your API key every time. Credentials are stored securely in `~/.mimic/credentials`.

{% hint style="info" %}
You can retrieve your API key from the [Mimic explorer](https://protocol.mimic.fi/) under your account settings.
{% endhint %}

#### 4.1. Usage

```bash
mimic login [options]
```

#### 4.2. Options

| Option                 | Description                             | Default   |
| ---------------------- | --------------------------------------- | --------- |
| `--profile, -p <name>` | Profile name to use for this credential | `default` |
| `--api-key, -k <key>`  | API key (non-interactive mode)          | -         |
| `--force-login, -f`    | Force login even if profile exists      | `false`   |

#### 4.3. Examples

```bash
# Interactive login (prompts for API key)
mimic login

# Login with a specific profile
mimic login --profile staging

# Non-interactive login with API key provided directly
mimic login --profile production --api-key YOUR_API_KEY

# Force overwrite existing profile without confirmation
mimic login --profile production --force-login
```

#### 4.4. Behavior

In interactive mode, the CLI prompts you to:

1. Enter your API key (masked input)
2. Enter a profile name (defaults to "default")

If a profile already exists, you'll be asked to confirm before overwriting it (unless `--force-login` is used).

{% hint style="info" %}
Profile names cannot contain `[`, `]`, or `=` characters.
{% endhint %}

***

### 5. Logout

Removes stored credentials for a specific profile. This is useful when you want to revoke local access or clean up old credentials.

#### 5.1. Usage

```bash
mimic logout [options]
```

#### 5.2. Options

| Option                 | Description              | Default   |
| ---------------------- | ------------------------ | --------- |
| `--profile, -p <name>` | Profile name to remove   | `default` |
| `--force, -f`          | Skip confirmation prompt | `false`   |

#### 5.3. Examples

```bash
# Remove credentials for the default profile (asks for confirmation)
mimic logout

# Remove credentials for a specific profile
mimic logout --profile staging

# Force removal without confirmation
mimic logout --force
```

***

### 6. Profiles

Lists all configured authentication profiles stored in `~/.mimic/credentials`. This is useful for checking which profiles are available and which one is set as default.

#### 6.1. Usage

```bash
mimic profiles
```

#### 6.2. Options

No options available for this command.

#### 6.3. Examples

```bash
# List all configured profiles
mimic profiles
```

#### 6.4. Output

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

* default (default)
* staging
* production

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

***

### 7. Deploy

Uploads your compiled function artifacts to IPFS and registers it into the Mimic Registry so others can discover it. This step pins the result under a CID so relayers can discover and execute it.

{% hint style="info" %}
You must retrieve your deployment key from the [Mimic explorer](https://protocol.mimic.fi/) under your account settings. If you don’t have one, create or copy it from there before running `deploy`.
{% endhint %}

#### 7.1. Usage

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

#### 7.2. Options

| Option                     | Description                                     | Default                         |
| -------------------------- | ----------------------------------------------- | ------------------------------- |
| `--api-key, -k <api-key>`  | Your account api key                            | -                               |
| `--input, -i <directory>`  | Directory containing the compiled artifacts     | `build`                         |
| `--output, -o <directory>` | Output directory for deployment CID             | `build`                         |
| `--url, -u <url>`          | Mimic Registry base URL                         | `https://api-protocol.mimic.fi` |
| `--skip-compile`           | Skip codegen and compile steps before uploading | `false`                         |
| `--profile, -p <name>`     | Profile name to use for the deployment.         | -                               |

{% hint style="info" %}
If neither an API key nor a profile is specified, the default profile will be used
{% endhint %}

#### 7.3. Examples

<pre class="language-bash"><code class="lang-bash"># Deploy from the default build directory, using your pre-configured key
<strong>yarn mimic deploy --api-key my-key
</strong>
# Deploy from the default build directory, using your pre-configured key
mimic deploy --api-key my-key

# Deploy from the default build directory, using the default profile
mimic deploy

# Deploy from the default build directory, using a specify profile
mimic deploy -p profile

# Deploy from a custom folder
mimic deploy --input ./dist

# Specify a different output path
mimic deploy --input ./dist --output ./dist

# Use a custom registry URL and skip local build steps
mimic deploy --url https://custom.registry --skip-compile
</code></pre>

#### 7.4. Validation and Outputs

Before uploading, the CLI validates that the input directory exists and includes:

* `manifest.json`
* `function.wasm`

On success:

* `build/CID.json` - Contains the IPFS Content Identifier for your deployed function

***

### 8. Configuration File (mimic.yaml)

For advanced use cases where you have multiple functions in a single project, you can use a `mimic.yaml` configuration file to define all functions and their build settings. This allows you to run CLI commands on multiple functions at once with optional filtering.

#### 8.1. File Format

Create a `mimic.yaml` file in your project root with the following structure:

```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
```

Each function entry requires:

| Field             | Description                             | Example                          |
| ----------------- | --------------------------------------- | -------------------------------- |
| `name`            | Unique identifier for the function      | `function-one`                   |
| `manifest`        | Path to the manifest.yaml file          | `./function-one/manifest.yaml`   |
| `function`        | Path to the AssemblyScript entry file   | `./function-one/src/function.ts` |
| `build-directory` | Output directory for compiled artifacts | `./function-one/build`           |
| `types-directory` | Output directory for generated types    | `./function-one/src/types`       |

#### 8.2. Usage with Commands

All CLI commands that support the `mimic.yaml` configuration (`codegen`, `compile`, `test`, `build` and `deploy`) will automatically use this file if it exists. When a `mimic.yaml` is present, the CLI will execute the command for each function defined in it.

{% hint style="info" %}
The `mimic test` command only uses the `--exclude` and `--include` filters for building, not for testing.
{% endhint %}

#### 8.3. Filtering Functions

You can selectively run commands on specific functions using include and exclude flags:

```bash
# Run codegen, compile, test, or deploy only for specific functions
yarn mimic compile --include function-one function-two

# Run commands for all functions except specific ones
yarn mimic codegen --exclude function-three

# These flags work with any command that supports mimic.yaml
yarn mimic deploy --include function-one --profile production
```

#### 8.4. Overriding Configuration

If you need to override the configuration file location or disable the configuration file entirely:

```bash
# Use a custom config file location
yarn mimic compile --config-file ./config/functions.yaml

# Ignore mimic.yaml and use defaults with explicit flags
yarn mimic compile --no-config --function ./src/function.ts
```

#### 8.5. Examples

**Example 1: Building Multiple Functions**

```bash
# Build all functions defined in mimic.yaml
yarn mimic build

# Build only specific functions
yarn mimic build --include function-one
```

**Example 2: Deploying Multiple Functions**

```bash
# Deploy all functions
yarn mimic deploy

# Deploy specific functions to production
yarn mimic deploy --include function-one function-two --profile production

# Deploy all except function-three to staging
yarn mimic deploy --exclude function-three
```

{% hint style="info" %}
The `mimic.yaml` file is optional and intended for advanced multi-function projects. Single-function projects can continue using individual command flags without creating a configuration file.
{% endhint %}

***

### 9. Test

Runs function tests using mocha. By default, it performs `codegen` and `compile` first, then executes `tests/**/*.spec.ts`.

#### 9.1. Usage

```bash
mimic test [options]
```

#### 9.2. Options

| Option                   | Description                                 | Default |
| ------------------------ | ------------------------------------------- | ------- |
| `--directory, -d <path>` | Function directory to run tests from        | `./`    |
| `--skip-compile`         | Skip codegen and compile steps before tests | `false` |

#### 9.3. Behavior

* If not skipped, runs `yarn mimic codegen` and `yarn mimic compile` in the target directory.
* Executes tests using mocha via tsx: `yarn tsx ./node_modules/mocha/bin/mocha.js tests/**/*.spec.ts`.


---

# 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/developers/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.