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

# malbox

> CLI reference for the malbox command-line tool

The `malbox` CLI is the unified entry point for Malbox. Use it to submit samples, manage analysis tasks and machines, register VM images, and administer the daemon.

This page covers the analysis commands that talk to a running daemon over HTTP. For host-local daemon administration (install, upgrade, config, providers, plugin installs), see [`malbox daemon`](/reference/cli/malbox-daemon).

<Note>
  Earlier releases shipped a separate `malboxctl` binary for daemon administration. Those commands now live under `malbox daemon`.
</Note>

## Global flags

These flags are available on every subcommand.

| Flag              | Type             | Default         | Description                                     |
| ----------------- | ---------------- | --------------- | ----------------------------------------------- |
| `--format`        | `text` \| `json` | `text`          | Output format                                   |
| `--api-url`       | `string`         | From `cli.toml` | Override the API base URL                       |
| `-v`, `--verbose` | -                | `false`         | Enable verbose output (sets log level to DEBUG) |
| `-y`, `--yes`     | -                | `false`         | Skip confirmation prompts                       |

The API URL defaults to the value in `~/.config/malbox/cli.toml`. If no config file exists, it falls back to `http://127.0.0.1:8080`.

## task

Manage analysis tasks.

### task submit

Submit a file for analysis.

```bash theme={null}
malbox task submit <file> [options]
```

| Argument / Flag     | Type       | Required | Default | Description                                 |
| ------------------- | ---------- | -------- | ------- | ------------------------------------------- |
| `file`              | `string`   | Yes      | -       | Path to the file to analyze                 |
| `--package`         | `string`   | No       | -       | Analysis package to use                     |
| `--module`          | `string`   | No       | -       | Analysis module to use                      |
| `--timeout`         | `integer`  | No       | -       | Analysis timeout in seconds                 |
| `--priority`        | `integer`  | No       | -       | Task priority (higher = more urgent)        |
| `--tags`            | `string[]` | No       | -       | Tags for the task (accepts multiple values) |
| `--owner`           | `string`   | No       | -       | Task owner                                  |
| `--memory`          | -          | No       | `false` | Enable memory dump                          |
| `--unique`          | -          | No       | `false` | Only analyze if the sample is unique        |
| `--enforce-timeout` | -          | No       | `false` | Enforce the timeout strictly                |

### task list

List all tasks.

```bash theme={null}
malbox task list
```

### task get

Get details and results of a specific task.

```bash theme={null}
malbox task get [id] [options]
```

| Argument / Flag | Type      | Required | Default | Description                                                                                                                  |
| --------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `integer` | No       | -       | Task ID. If omitted, an interactive fuzzy-select menu is shown.                                                              |
| `--result`      | `integer` | No       | -       | Fetch a specific result by its ID. JSON results are pretty-printed to a terminal; binary results are written raw when piped. |

## machine

Manage analysis machines.

### machine list

List all machines.

```bash theme={null}
malbox machine list
```

### machine get

Get details of a specific machine.

```bash theme={null}
malbox machine get [machine]
```

| Argument  | Type     | Required | Default | Description                                                                |
| --------- | -------- | -------- | ------- | -------------------------------------------------------------------------- |
| `machine` | `string` | No       | -       | Machine name or ID. If omitted, an interactive fuzzy-select menu is shown. |

### machine provision

Run a provisioning step against a machine.

```bash theme={null}
malbox machine provision [machine] --provisioner <type> [options]
```

| Argument / Flag | Type       | Required | Default | Description                                                                |
| --------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------- |
| `machine`       | `string`   | No       | -       | Machine name or ID. If omitted, an interactive fuzzy-select menu is shown. |
| `--provisioner` | `string`   | Yes      | -       | Provisioner type (for example, `ansible` or `native`)                      |
| `--snapshot`    | `string`   | No       | -       | Snapshot name to create after provisioning                                 |
| `--revert-to`   | `string`   | No       | `base`  | Snapshot to revert to before provisioning                                  |
| `--config`      | `string`   | No       | -       | Provisioner config as JSON (for example, `'{"playbook": "setup.yml"}'`)    |
| `--plugins`     | `string[]` | No       | -       | Guest plugin names to deploy (resolved from the daemon's plugin registry)  |

### machine provision-history

List provision run history for a machine.

```bash theme={null}
malbox machine provision-history [machine]
```

| Argument  | Type     | Required | Default | Description                                                                |
| --------- | -------- | -------- | ------- | -------------------------------------------------------------------------- |
| `machine` | `string` | No       | -       | Machine name or ID. If omitted, an interactive fuzzy-select menu is shown. |

### machine snapshot list

List snapshots for a machine.

```bash theme={null}
malbox machine snapshot list [machine]
```

| Argument  | Type     | Required | Default | Description                                                                |
| --------- | -------- | -------- | ------- | -------------------------------------------------------------------------- |
| `machine` | `string` | No       | -       | Machine name or ID. If omitted, an interactive fuzzy-select menu is shown. |

### machine snapshot delete

Delete a snapshot and its associated provision runs.

```bash theme={null}
malbox machine snapshot delete [machine] [snapshot_name]
```

| Argument        | Type     | Required | Default | Description                                                                |
| --------------- | -------- | -------- | ------- | -------------------------------------------------------------------------- |
| `machine`       | `string` | No       | -       | Machine name or ID. If omitted, an interactive fuzzy-select menu is shown. |
| `snapshot_name` | `string` | No       | -       | Snapshot name. If omitted, an interactive fuzzy-select menu is shown.      |

## image

Manage VM images.

### image register

Register a new VM image.

```bash theme={null}
malbox image register --name <name> --platform <platform> --arch <arch> --path <path> [options]
```

| Flag             | Type                 | Required | Default | Description                                   |
| ---------------- | -------------------- | -------- | ------- | --------------------------------------------- |
| `--name`         | `string`             | Yes      | -       | Image name                                    |
| `--platform`     | `windows` \| `linux` | Yes      | -       | Target platform                               |
| `--arch`         | `x64` \| `x86`       | Yes      | -       | Target architecture                           |
| `--path`         | `string`             | Yes      | -       | Path to the image file                        |
| `--image-format` | `string`             | No       | -       | Image format (for example, `qcow2` or `vmdk`) |
| `--description`  | `string`             | No       | -       | Image description                             |

### image list

List all registered images.

```bash theme={null}
malbox image list
```

### image get

Get details of a specific image.

```bash theme={null}
malbox image get <name>
```

| Argument | Type     | Required | Description |
| -------- | -------- | -------- | ----------- |
| `name`   | `string` | Yes      | Image name  |

### image delete

Delete an image.

```bash theme={null}
malbox image delete <name>
```

| Argument | Type     | Required | Description |
| -------- | -------- | -------- | ----------- |
| `name`   | `string` | Yes      | Image name  |

## plugin

View analysis plugins registered with the running daemon. To install, update, or remove plugins on the host, use [`malbox daemon plugin`](/reference/cli/malbox-daemon#plugin).

### plugin list

List registered plugins.

```bash theme={null}
malbox plugin list [options]
```

| Flag     | Type     | Required | Default | Description                                            |
| -------- | -------- | -------- | ------- | ------------------------------------------------------ |
| `--type` | `string` | No       | -       | Filter by plugin type (for example, `guest` or `host`) |

## completion

Generate shell completions.

```bash theme={null}
malbox completion <shell>
```

| Argument | Type                                                  | Required | Description  |
| -------- | ----------------------------------------------------- | -------- | ------------ |
| `shell`  | `bash` \| `zsh` \| `fish` \| `elvish` \| `powershell` | Yes      | Target shell |

To install completions, redirect the output to the appropriate location for your shell:

```bash theme={null}
# Bash
malbox completion bash > ~/.local/share/bash-completion/completions/malbox

# Zsh
malbox completion zsh > ~/.zfunc/_malbox

# Fish
malbox completion fish > ~/.config/fish/completions/malbox.fish
```

## Configuration

The `malbox` CLI reads its configuration from `~/.config/malbox/cli.toml`:

```toml theme={null}
[api]
url = "http://127.0.0.1:8080"
```

This file is created automatically by [`malbox daemon config init`](/reference/cli/malbox-daemon#config-init).

## Environment variables

| Variable   | Description                                                                                                                                                                                                          |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RUST_LOG` | Override the log level filter. Takes precedence over `--verbose`. Uses standard [`tracing_subscriber::EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) syntax. |