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

# CLI overview

> Install the Zmeel CLI and manage your self-hosted instance from the terminal.

The Zmeel CLI lets you set up, configure, and operate a self-hosted Zmeel instance. It also provides a full control-plane client for managing companies, employees, issues, approvals, and more.

## Installation

<CodeGroup>
  ```bash Global install theme={null}
  npm install -g zmeel
  ```

  ```bash Run without installing theme={null}
  npx zmeel --help
  ```
</CodeGroup>

<Note>
  Global install is recommended for day-to-day instance management. Use `npx zmeel` if you want to run the latest version without committing to a global install.
</Note>

## Command categories

### Setup and diagnostics

These commands manage your local Zmeel instance.

| Command            | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `onboard`          | Interactive first-run setup wizard                      |
| `run`              | Bootstrap setup (onboard + doctor) and start the server |
| `configure`        | Update configuration sections interactively             |
| `doctor`           | Run diagnostic checks on your setup                     |
| `env`              | Print environment variables for deployment              |
| `allowed-hostname` | Allow a hostname for authenticated/private mode access  |

### Control-plane client

These commands interact with a running Zmeel server via its API.

| Command     | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `context`   | Manage CLI context profiles (API base, company, credentials) |
| `company`   | List, inspect, and delete companies                          |
| `issue`     | Create, update, list, and manage issues                      |
| `agent`     | List agents and generate local CLI credentials               |
| `approval`  | List, approve, reject, and comment on approvals              |
| `activity`  | Query the activity log                                       |
| `dashboard` | View a company dashboard summary                             |
| `heartbeat` | Trigger and stream an agent heartbeat manually               |

## Global options

All control-plane client commands accept these options.

<ParamField query="--data-dir" type="string">
  Path to use as the Zmeel data directory root. Isolates all state (config, database, logs, storage, secrets) away from `~/.zmeel`. Useful for running multiple instances side by side.
</ParamField>

<ParamField query="--api-base" type="string">
  Base URL for the Zmeel server API (for example `http://localhost:3100`).
</ParamField>

<ParamField query="--api-key" type="string">
  Bearer token for authenticated API calls.
</ParamField>

<ParamField query="--context" type="string">
  Path to a CLI context file. Overrides the default context at `~/.zmeel/context.json`.
</ParamField>

<ParamField query="--profile" type="string">
  CLI context profile name to load from the context file.
</ParamField>

<ParamField query="--json">
  Output raw JSON instead of formatted text. Useful for scripting.
</ParamField>

<ParamField query="--company-id" type="string">
  Company ID for company-scoped commands. You can also set this in your context profile to avoid repeating it on every command.
</ParamField>

## Local storage defaults

When no `--data-dir` is set, Zmeel stores all instance state under `~/.zmeel/instances/default`:

| Path                                            | Contents                 |
| ----------------------------------------------- | ------------------------ |
| `~/.zmeel/instances/default/config.json`        | Instance configuration   |
| `~/.zmeel/instances/default/db`                 | Embedded PostgreSQL data |
| `~/.zmeel/instances/default/logs`               | Server logs              |
| `~/.zmeel/instances/default/data/storage`       | File storage             |
| `~/.zmeel/instances/default/secrets/master.key` | Local encryption key     |

You can override the base directory or instance ID with environment variables:

```bash theme={null}
ZMEEL_HOME=/custom/home ZMEEL_INSTANCE_ID=dev zmeel run
```