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

# minicli

> Use the minicli command-line tool to define, build, and manage private Minimus images from your terminal or CI/CD pipeline.

minicli is the Minimus command-line tool for managing private images. Use it to define, build, and manage private images as code directly from your terminal or CI/CD pipeline.

minicli is also natively **AI-agent ready**. With the `generate-skills` command, you can equip AI coding assistants such as Cursor, Claude Code, Windsurf, or GitHub Copilot to create, configure, and inspect your Minimus private images using natural language prompts.

## Installation & authentication

Download the latest binary and authenticate to minicli. See [minicli installation](/manage/minicli)

## Commands

### 1. version

Display the current version of the minicli binary. Does not require authentication.

<CodeGroup>
  ```text minicli version lookup theme={null}
  minicli version
  ```

  ```text output example theme={null}
  minicli version 1.0.5
  ```
</CodeGroup>

### 2. generate-skills

`minicli` is designed to be natively **AI-agent ready**. You can empower your favorite AI coding assistants (such as Cursor, Windsurf, GitHub Copilot, or other local LLM tools) to natively understand and interact with `minicli`.

Because different AI tools look for project instructions in different directories, use the `--output` flag to add the skills in the appropriate folder for your specific assistant.

```bash theme={null}
minicli generate-skills --output {path-to-your-ai-context-folder}
```

| Flag       | Shorthand | Description                                                               |
| ---------- | --------- | ------------------------------------------------------------------------- |
| `--output` | `-o`      | Path to the AI assistant's context folder where skills should be written. |
| `--help`   | `-h`      | Prints the help menu and available flags                                  |

#### Example: Equipping Cursor

Cursor looks for custom skills in the `.cursor/skills` directory of your project.

```bash theme={null}
minicli generate-skills --output <path-to-your-project>/.cursor/skills
# example minicli generate-skills --output ~/GolandProjects/awesomeProject/.cursor/skills
```

Once generated in the correct folder, your AI agent will automatically pick up these skills, allowing it to act as an expert Minimus assistant within your project.

#### Example AI workflows with minicli

Once the skills have been generated, you can open your AI chat interface and start prompting. Here are a few ways to interact with your agent:

<AccordionGroup>
  <Accordion title="Create a new private image">
    Ask the agent to scaffold a completely new image using a specific starter image and inject environment variables and packages.

    > "Using minicli skills, create a new private image called `my-test-image-skills` based on the `go` starter image, with packages `curl` and `git`, and environment variable `ENV=production`. Walk me through the steps."
  </Accordion>

  <Accordion title="Modify an existing image">
    The agent can read your existing image recipes, update them, and re-apply the changes without you needing to manually edit the YAML or run the CLI commands yourself.

    > "I have an existing private image called `demo-image`. Export its config, add the `agetty` and `agetty-openrc` packages to it, as well as the env var `SOMETHING=INBAR` and the file bundle `bb-2`, and re-apply."
  </Accordion>

  <Accordion title="Query and inspect images">
    Let the agent do the querying for you when you need to check what's currently running or inspect the exact configuration of a specific image.

    > "Ok, now list the images, then get all details on the `demo-image` image and print them to me."
  </Accordion>
</AccordionGroup>

### 3. image init

Create a local YAML template with all supported image fields, pre-populated with empty values for you to fill in.

<CodeGroup>
  ```text image init theme={null}
  minicli image init
  ```

  ```text custom path theme={null}
  minicli image init --output path/custom.yaml
  ```

  ```text default output theme={null}
  YAML template successfully created!
  Saved to: image.yaml
  ```
</CodeGroup>

| Flag       | Shorthand | Description                                           |
| ---------- | --------- | ----------------------------------------------------- |
| `--output` | `-o`      | File path to save the template. Default: `image.yaml` |
| `--help`   | `-h`      | Prints the help menu and available flags              |

The generated file will include notes to help clarify its use. Below is the default output and the bare structure stripped of the notes:

<CodeGroup>
  ```text default image.yaml expandable lines theme={null}
  schemaVersion: v1

  # Required. The private image Unique name is used as the remote identifier.
  name: ""

  # Required. The private image builds on a starter image from your organization's subscribed images.
  starterImage: ""

  # Optional. List of additional packages to install in the private image alongside the starter image packages. For example:
  # additionalPackages:
  #   - pkg1
  #   - pkg2
  additionalPackages:

  # Optional. Environment variables to set in the private image (map of KEY: VALUE). String values only. For example:
  # envVars:
  #   Key1: "value1"
  #   key2: "value2"
  envVars:

  # Optional. File bundles to include in the private image (list of file bundle IDs). For example:
  # fileBundles:
  #   - bundle-id1
  #   - bundle-id2
  fileBundles:

  # Optional. Free-text description of the private image to be shown in the gallery UI.
  description: ""
  ```

  ```text bare structure (without notes) lines theme={null}
  schemaVersion: v1
  name:
  starterImage:
  additionalPackages:
  envVars:
  fileBundles:
  description:
  ```
</CodeGroup>

Once you fill in an image recipe, it might look like this:

```text image recipe example lines theme={null}
schemaVersion: v1
name: trino-plugins
starterImage: trino
additionalPackages:
    - trino-plugin-mysql
    - trino-plugin-cassandra
    - trino-plugin-ai-functions
envVars: {}
fileBundles: []
description: added trino-plugin-ai-functions trino-plugin-cassandra trino-plugin-mysql
```

### 4. image apply

Create or update a private image recipe from a local YAML file. Follow up with the command `image build submit` to trigger a build of your updated image.

<CodeGroup>
  ```bash apply a private image recipe theme={null}
  minicli image apply --file images/custom.yaml
  ```

  ```text output example wrap theme={null}
  Success! Applied updates to the private image recipe!

  Image name: my-image

  Run 'minicli image build submit --name img' to trigger an image build using the updated recipe.
  ```
</CodeGroup>

| Flag     | Shorthand | Description                              |
| -------- | --------- | ---------------------------------------- |
| `--file` | `-f`      | Required. Path to the YAML file          |
| `--help` | `-h`      | Prints the help menu and available flags |

If the YAML is invalid, minicli returns a detailed list of errors, for example:

```text theme={null}
✗ YAML file validation failed:
  - envVars: "INVALID_KEY" is not a valid key=value format.
  - other: invalid field (doesn't exist).
```

### 5. image build submit

Trigger an asynchronous build for a private image. Returns immediately without waiting for the build to complete.

<CodeGroup>
  ```text image build submit theme={null}
  minicli image build submit --name my-image
  ```

  ```text output example theme={null}
  Success! Private image build was triggered!
  Run 'minicli image build status --name trino-plugins' to track progress.
  ```
</CodeGroup>

* You can run `minicli image build status --name {private-image-name}`to track progress.
* Once the build is complete, you can view the image's detailed build report in the Creator UI. This is particularly helpful if the build did not succeed. The image build report will show you which packages were incompatible. [Learn more](/advanced-tooling/image-creator)

| Flag     | Shorthand | Description                              |
| -------- | --------- | ---------------------------------------- |
| `--name` | `-n`      | Name of the private image to build       |
| `--help` | `-h`      | Prints the help menu and available flags |

### 6. image build status

Look up the current status of a private image build.

<CodeGroup>
  ```text image build status theme={null}
  minicli image build status --name my-image
  ```

  ```text command example theme={null}
   minicli image build status --name trino-plugins
  ```

  ```text output example theme={null}
  Build Status: BUILDING
  Last updated: 2026-06-02 14:25:12
  ```
</CodeGroup>

| Flag     | Shorthand | Description                              |
| -------- | --------- | ---------------------------------------- |
| `--name` | `-n`      | Name of the private image                |
| `--help` | `-h`      | Prints the help menu and available flags |

### 7. image export

Retrieve the configuration of a remote private image and output it in YAML file. You can export private image recipes to track changes in git.

<CodeGroup>
  ```text image export theme={null}
  minicli image export --name my-image
  minicli image export --name my-image --output export.yaml
  ```

  ```text output example theme={null}
  Success! Image recipe exported for private image: my-nginx
  ```
</CodeGroup>

| Flag       | Shorthand | Description                                           |
| ---------- | --------- | ----------------------------------------------------- |
| `--name`   | `-n`      | Name of the private image to export                   |
| `--output` | `-o`      | File path to write to. If omitted, prints to terminal |
| `--help`   | `-h`      | Prints the help menu and available flags              |

YAML output example:

```yaml theme={null}
schemaVersion: v1
name: test
starterImage: go
additionalPackages:
    - 7zip
envVars: {}
fileBundles: []
description: "Test private image"
```

### 8. image list

List your Minimus private images:

<CodeGroup>
  ```text list private images theme={null}
  minicli image list
  ```

  ```text table output example (default) theme={null}
  PRIVATE IMAGES

  ID    NAME                    STARTER IMAGE   STATUS     CREATED               UPDATED
  289   trino-plugins           trino           COMPLETE   2026-05-03 14:15:06   2026-06-02 14:35:58
  244   rabbitmq-cert           rabbitmq        COMPLETE   2026-04-12 13:27:21   2026-06-01 12:24:08
  245   mongo-cert              mongo           COMPLETE   2026-04-12 13:43:15   2026-05-31 03:23:58
  ```

  ```json json output example theme={null}
  ~$ minicli image list -o json
  [
    {
      "additionalPackages": [
        "trino-plugin-mysql",
        "trino-plugin-cassandra",
        "trino-plugin-ai-functions"
      ],
      "buildStatus": "COMPLETE",
      "createdAt": "2026-05-03T14:15:06.946784Z",
      "description": "added trino-plugin-ai-functions trino-plugin-cassandra trino-plugin-mysql",
      "id": 289,
      "name": "trino-plugins",
      "starterImage": "trino",
      "updatedAt": "2026-06-02T14:35:58.035916Z"
    },
    {
      "additionalPackages": [
        "go-1.22",
        "7zip-doc"
      ],
      "buildStatus": "COMPLETE",
      "createdAt": "2025-11-23T14:48:00.376719Z",
      "description": "Some description",
      "id": 79,
      "name": "test-elasticsearch",
      "starterImage": "elasticsearch",
      "updatedAt": "2026-06-02T13:00:04.655249Z"
    }
  ```
</CodeGroup>

| Flag        | Shorthand | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `--private` | `-p`      | List private images. Default: `true`                 |
| `--starter` | `-s`      | List starter images available in your license        |
| `--output`  | `-o`      | `table` (default) or `json`. Prints to the terminal. |
| `--help`    | `-h`      | Prints the help menu and available flags             |

You can also list the starter images available in your license for building private images:

<CodeGroup>
  ```bash list starter images theme={null}
  minicli image list -s
  ```

  ```json table output example theme={null}
  STARTER IMAGES
  The following images are included in your account license:
  nginx
  postgres
  cassandra
  ```

  ```json json output example theme={null}
  ~$ minicli image list -s -o json
  {
    "allImagesEnabled": true,
    "images": []
  }
  ```
</CodeGroup>

### 9. image get

Get the full details of a private image.

<CodeGroup>
  ```bash image get theme={null}
  minicli image get --name my-image
  ```

  ```text table output example (default) theme={null}
  Image Details:
  -----------------------------------
  ID:                  289
  Name:                trino-plugins
  Starter Image:       trino
  Additional Packages: trino-plugin-mysql, trino-plugin-cassandra, trino-plugin-ai-functions
  Env vars:
  Build Status:        COMPLETE
  Created At:          2026-05-03 14:15:06
  Updated At:          2026-06-02 14:35:58
  Description:         added trino-plugin-ai-functions trino-plugin-cassandra trino-plugin-mysql
  File Bundles:
  ```

  ```json json output example theme={null}
  minicli image get --name trino-plugins -o json
  {
    "additionalPackages": [
      "trino-plugin-mysql",
      "trino-plugin-cassandra",
      "trino-plugin-ai-functions"
    ],
    "buildStatus": "COMPLETE",
    "createdAt": "2026-05-03T14:15:06.946784Z",
    "description": "added trino-plugin-ai-functions trino-plugin-cassandra trino-plugin-mysql",
    "id": 289,
    "name": "trino-plugins",
    "starterImage": "trino",
    "updatedAt": "2026-06-02T14:35:58.035916Z"
  }
  ```
</CodeGroup>

| Flag       | Shorthand | Description                                         |
| ---------- | --------- | --------------------------------------------------- |
| `--name`   | `-n`      | Name of the private image                           |
| `--output` | `-o`      | `table` (default) or `json`. Prints to the terminal |
| `--help`   | `-h`      | Prints the help menu and available flags            |

### 10. bundle list

List all file bundles in your account. File bundles are used to include public keys for internal PKIs (Public Key Infrastructure certificates) and override configuration files and more. [Learn more](/advanced-tooling/file-bundles)

<CodeGroup>
  ```bash list file bundles theme={null}
  minicli bundle list
  ```

  ```bash table output example (default) theme={null}
  ID    NAME                         DESCRIPTION   TYPE      FILES                         PATH                                CREATED               UPDATED
  46    nginx.conf                                 generic   [nginx.conf (0 KB)]           /etc/nginx                          2026-02-17 13:51:54   2026-05-26 09:09:26
  224   mongo-client-cert                          certs     [cert-test.cert (2 KB)]       /usr/local/share/ca-certificates/   2026-04-12 13:48:59   2026-04-12 14:30:46
  223   mongo-cert                                 certs     [client.pem (3 KB)]           /usr/local/share/ca-certificates/   2026-04-12 13:43:02   2026-04-12 13:43:02
  222   RabbitMQ-certs                             certs     [ca_certificate.pem (1 KB)]   /usr/local/share/ca-certificates/   2026-04-12 13:26:52   2026-04-12 13:26:52
  ```

  ```text json output example theme={null}
  ~$ minicli bundle list --output json
  [
    {
      "createdAt": "2026-02-17T13:51:54.803871Z",
      "files": [
        {
          "name": "nginx.conf",
          "sizeBytes": 105
        }
      ],
      "id": 46,
      "name": "nginx.conf again and again",
      "path": "/etc/nginx",
      "type": "generic",
      "updatedAt": "2026-05-26T09:09:26.297413Z"
    },
    {
      "createdAt": "2026-04-12T13:48:59.213012Z",
      "files": [
        {
          "name": "cert-test.cert",
          "sizeBytes": 2010
        }
      ],
      "id": 224,
      "name": "mongo-client-cert",
      "path": "/usr/local/share/ca-certificates/",
      "type": "certs",
      "updatedAt": "2026-04-12T14:30:46.213012Z"
    }
  ```
</CodeGroup>

| Flag       | Shorthand | Description                                          |
| :--------- | :-------- | :--------------------------------------------------- |
| `--output` | `-o`      | `table` (default) or `json`. Prints to the terminal. |
| `--help`   | `-h`      | Prints the help menu and available flags             |

### 11. image delete

Delete a private image from your account. Prompts for confirmation unless `--force` is passed. The image will also be removed from Creator and will no longer be available for use.

<CodeGroup>
  ```bash image delete theme={null}
  minicli image delete --name my-image
  ```

  ```bash skip confirmation theme={null}
  minicli image delete --name my-image --force
  ```

  ```text output example theme={null}
  Are you sure you want to delete "test"? This action cannot be undone. [y/N]: y
  Image "test" successfully deleted!
  ```
</CodeGroup>

| Flag      | Shorthand | Description                              |
| --------- | --------- | ---------------------------------------- |
| `--name`  | `-n`      | Name of the private image to delete      |
| `--force` | `-f`      | Skip the confirmation prompt             |
| `--help`  | `-h`      | Prints the help menu and available flags |