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

# CLI Reference

> Complete reference for the meepagateway command-line interface.

The `meepagateway` CLI manages your gateway from the terminal. Management commands talk to a running gateway instance via the Captain API.

## Global flags

These flags apply to all commands.

| Flag              | Env var     | Default                       | Description                                         |
| ----------------- | ----------- | ----------------------------- | --------------------------------------------------- |
| `--config <PATH>` | —           | `~/.meepagateway/config.yaml` | Config file path (used by `start` and `setup` only) |
| `--url <URL>`     | `MEEPA_URL` | auto-detected from config     | Gateway URL for management commands                 |
| `--json`          | —           | false                         | Output as JSON instead of human-readable text       |
| `-y, --yes`       | —           | false                         | Skip confirmation prompts                           |

## Authentication

Management commands require an API key. Set it via environment variable:

```bash theme={null}
export MEEPA_API_KEY="cptn_abc123..."
export MEEPA_URL="http://localhost:63372"  # optional, auto-detected
```

Create an API key via the Captain Dashboard or `meepagateway api-key create`.

## Interactive mode

Commands that accept an agent ID will open a TUI picker when the ID is omitted. Commands that accept flags will prompt interactively when flags are omitted.

***

## Server commands

### `start`

Start the gateway. Default when no command is given.

```bash theme={null}
meepagateway start
meepagateway start --port 8092 --bind 0.0.0.0
meepagateway --config /path/to/config.yaml start
```

| Flag            | Description                     |
| --------------- | ------------------------------- |
| `--port <PORT>` | Server port (overrides config)  |
| `--bind <ADDR>` | Bind address (overrides config) |

### `setup`

Run the setup wizard. Works even when a config already exists.

```bash theme={null}
meepagateway setup
```

### `stop`

Stop a running gateway (SIGTERM, then SIGKILL after timeout).

```bash theme={null}
meepagateway stop
```

### `restart`

Stop and re-launch with the same arguments.

```bash theme={null}
meepagateway restart
```

### `status`

Show gateway status. No authentication required.

```bash theme={null}
meepagateway status
meepagateway status --json
```

### `update`

Check for updates and self-update the binary.

```bash theme={null}
meepagateway update           # download and install latest
meepagateway update --check   # check without installing
```

### `uninstall`

Remove the binary and skills catalog.

```bash theme={null}
meepagateway uninstall          # binary only
meepagateway uninstall --purge  # also removes ~/.meepagateway/ agent data
```

***

## Config commands

### `config show`

Show current configuration (secrets redacted).

```bash theme={null}
meepagateway config show
meepagateway config show --json
```

### `config raw`

Show the raw config file contents.

```bash theme={null}
meepagateway config raw
```

### `config edit`

Open config in `$EDITOR`, then save changes to the gateway.

```bash theme={null}
meepagateway config edit
```

### `config validate`

Validate config without saving.

```bash theme={null}
meepagateway config validate
meepagateway config validate --file ./config.yaml
```

### `config reload`

Reload config from disk.

```bash theme={null}
meepagateway config reload
```

### `config reset`

Reset config to defaults (preserves authentication settings).

```bash theme={null}
meepagateway config reset
```

***

## Agent commands

### `agent list`

List all agents.

```bash theme={null}
meepagateway agent list
meepagateway agent list --json
```

### `agent show [ID]`

Show details for an agent.

```bash theme={null}
meepagateway agent show meepa
```

### `agent create`

Create a new agent. Run without flags for interactive mode.

```bash theme={null}
meepagateway agent create
meepagateway agent create --name "Coder" --provider anthropic --model claude-opus-4-6
```

| Flag                   | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `--name <NAME>`        | Display name                                   |
| `--id <ID>`            | Agent ID (auto-generated from name if omitted) |
| `--provider <NAME>`    | LLM provider override                          |
| `--model <MODEL>`      | Model override                                 |
| `--max-iterations <N>` | Max tool call iterations per message           |
| `--default`            | Set as the default agent                       |

### `agent update [ID]`

Update agent settings. Run without flags for interactive mode.

```bash theme={null}
meepagateway agent update meepa --model claude-opus-4-6 --max-iterations 20
```

### `agent delete [ID]`

Delete an agent.

```bash theme={null}
meepagateway agent delete coder
meepagateway agent delete coder -y
```

***

## Soul commands

The soul is an agent's personality and system prompt — a Markdown file (`SOUL.md`).

### `agent soul show [ID]`

```bash theme={null}
meepagateway agent soul show meepa
```

### `agent soul edit [ID]`

Open soul in `$EDITOR`.

```bash theme={null}
meepagateway agent soul edit meepa
```

### `agent soul set [ID]`

Set soul from a local file.

```bash theme={null}
meepagateway agent soul set meepa --file ./soul.md
```

***

## Memory and user profile commands

### `agent memory show/edit/set [ID]`

Manage an agent's `MEMORY.md` (long-term notes).

```bash theme={null}
meepagateway agent memory show meepa
meepagateway agent memory edit meepa
meepagateway agent memory set meepa --file ./memory.md
```

### `agent user show/edit/set [ID]`

Manage an agent's `USER.md` (user profile).

```bash theme={null}
meepagateway agent user show meepa
meepagateway agent user edit meepa
meepagateway agent user set meepa --file ./user.md
```

***

## Skill commands

### `agent skill list [ID]`

List skills for an agent.

```bash theme={null}
meepagateway agent skill list meepa
```

### `agent skill show [ID] <NAME>`

Show a skill's content.

```bash theme={null}
meepagateway agent skill show meepa summarize
```

### `agent skill add [ID] <NAME>`

Add or update a skill from a file.

```bash theme={null}
meepagateway agent skill add meepa summarize --file ./skills/summarize.md
```

### `agent skill remove [ID] <NAME>`

Remove a skill.

```bash theme={null}
meepagateway agent skill remove meepa summarize
```

### `agent skill catalog`

List skills available in the bundled catalog.

```bash theme={null}
meepagateway agent skill catalog
```

### `agent skill install [ID] <NAME>`

Install a skill from the bundled catalog.

```bash theme={null}
meepagateway agent skill install meepa web-search
```

### `agent skill install-url [ID] <URL>`

Install a skill from a GitHub repository.

```bash theme={null}
meepagateway agent skill install-url meepa owner/repo
```

***

## Connector commands

### `agent connector list [ID]`

List connectors for an agent.

```bash theme={null}
meepagateway agent connector list meepa
```

### `agent connector add [ID]`

Add a connector. Run without flags for interactive mode.

```bash theme={null}
meepagateway agent connector add
meepagateway agent connector add meepa \
  --name chat --type meepachat \
  --connector-url "wss://chat.example.com/api/bot-gateway" \
  --bot-token "BOT_ID.SECRET"
```

| Flag                    | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `--name <NAME>`         | Connector name                                                    |
| `--type <TYPE>`         | Platform: `meepachat`, `discord`, `telegram`, `slack`, `whatsapp` |
| `--connector-url <URL>` | Server URL (meepachat)                                            |
| `--bot-token <TOKEN>`   | Bot token                                                         |
| `--app-token <TOKEN>`   | App-level token (Slack Socket Mode)                               |
| `--guild-ids <IDS>`     | Comma-separated guild IDs (Discord)                               |

### `agent connector edit [ID] [NAME]`

Edit a connector interactively.

```bash theme={null}
meepagateway agent connector edit meepa discord
```

### `agent connector remove [ID] <NAME>`

Remove a connector.

```bash theme={null}
meepagateway agent connector remove meepa discord
```

### `agent connector test`

Test a connector connection without saving.

```bash theme={null}
meepagateway agent connector test \
  --type meepachat \
  --connector-url "wss://chat.example.com/api/bot-gateway" \
  --bot-token "BOT_ID.SECRET"
```

***

## MCP command

### `agent mcp [ID]`

Open an agent's `.mcp.json` in `$EDITOR`. MCP servers are not configured in the main config file — they live at `~/.meepagateway/agents/{id}/.mcp.json`.

```bash theme={null}
meepagateway agent mcp meepa
```

***

## Cron commands

### `agent cron list [ID]`

List cron jobs for an agent.

```bash theme={null}
meepagateway agent cron list meepa
```

### `agent cron show [ID] [JOB_ID]`

Show cron job details.

```bash theme={null}
meepagateway agent cron show meepa <job-id>
```

### `agent cron create [ID]`

Create a scheduled job. Run without flags for interactive mode. Exactly one of `--every`, `--cron`, or `--at` is required in non-interactive mode.

```bash theme={null}
# Interval schedule
meepagateway agent cron create meepa \
  --name "hourly-digest" \
  --message "Summarize recent activity" \
  --every 1h

# Cron expression (7-field, with seconds)
meepagateway agent cron create meepa \
  --name "weekday-morning" \
  --message "Post the morning report" \
  --cron "0 0 9 * * 1-5 *"

# One-shot
meepagateway agent cron create meepa \
  --name "reminder" \
  --message "Send the deadline reminder" \
  --at "2026-12-31T09:00:00Z" \
  --delete-after-run
```

| Flag                          | Description                        |
| ----------------------------- | ---------------------------------- |
| `--name <NAME>`               | Job name                           |
| `--message <MSG>`             | Prompt injected when the job fires |
| `--every <INTERVAL>`          | Interval (e.g. `30m`, `1h`, `24h`) |
| `--cron <EXPR>`               | 7-field cron expression            |
| `--at <DATETIME>`             | One-shot ISO 8601 datetime         |
| `--delivery-connector <NAME>` | Target connector for output        |
| `--delivery-channel <ID>`     | Target channel for output          |
| `--model <MODEL>`             | Model override for this job        |
| `--max-iterations <N>`        | Max iterations for this job        |
| `--disabled`                  | Create in disabled state           |
| `--delete-after-run`          | Delete after successful execution  |

### `agent cron update [ID] [JOB_ID]`

Update a cron job.

```bash theme={null}
meepagateway agent cron update meepa <job-id> --message "New prompt" --every 2h
meepagateway agent cron update meepa <job-id> --disabled
```

### `agent cron delete [ID] [JOB_ID]`

Delete a cron job.

```bash theme={null}
meepagateway agent cron delete meepa <job-id>
```

### `agent cron run [ID] [JOB_ID]`

Trigger a cron job immediately.

```bash theme={null}
meepagateway agent cron run meepa <job-id>
```

***

## Credentials and secrets commands

### `agent credentials [ID]`

Launch the interactive credentials setup wizard for an agent.

```bash theme={null}
meepagateway agent credentials meepa
```

### `agent secrets [ID]`

Manage SOPS-encrypted secrets for an agent via a TUI.

```bash theme={null}
meepagateway agent secrets meepa
meepagateway agent secrets meepa --show    # list keys (values hidden)
meepagateway agent secrets meepa --reveal  # show decrypted values
```

### `secrets list`

List gateway-level secret keys.

```bash theme={null}
meepagateway secrets list
```

### `secrets set/get/remove`

Manage gateway-level secrets.

```bash theme={null}
meepagateway secrets set discord.bot_token "Bot.Token123"
meepagateway secrets get discord.bot_token
meepagateway secrets remove discord.bot_token
```

***

## API key commands

### `api-key list`

List all Captain API keys.

```bash theme={null}
meepagateway api-key list
```

### `api-key create <NAME>`

Create a new API key. The full key is shown once and cannot be retrieved later.

```bash theme={null}
meepagateway api-key create "ci-deploy"
```

### `api-key revoke <ID>`

Revoke an API key.

```bash theme={null}
meepagateway api-key revoke <id>
```

***

## Container commands

### `container status`

Show container mode configuration and image status.

```bash theme={null}
meepagateway container status
```

### `container build`

Build the container image.

```bash theme={null}
meepagateway container build
meepagateway container build --force
```

### `container list`

List container images.

```bash theme={null}
meepagateway container list
```

### `container remove <TAG>` / `container clean`

Remove a specific image or all container images.

```bash theme={null}
meepagateway container remove v1
meepagateway container clean
```

***

## Webhook commands

### `webhook setup`

Run the interactive webhook setup wizard for incoming webhooks (Telegram, WhatsApp).

```bash theme={null}
meepagateway webhook setup
meepagateway webhook setup --mode cloudflare_tunnel --token "..."
meepagateway webhook setup --mode reverse_proxy --public-url "https://bot.example.com"
```

Supported modes: `cloudflare_tunnel`, `reverse_proxy`, `tailscale`.

### `webhook status`

Show webhook configuration and status.

```bash theme={null}
meepagateway webhook status
```

### `webhook enable` / `webhook disable`

```bash theme={null}
meepagateway webhook enable
meepagateway webhook disable
```

***

## Tips

**JSON output for scripting:**

```bash theme={null}
meepagateway --json agent list | jq '.[].id'
```

**Remote management:**

```bash theme={null}
export MEEPA_URL="https://gateway.example.com"
export MEEPA_API_KEY="cptn_..."
meepagateway agent list
```

**Non-interactive for CI/CD:**

```bash theme={null}
meepagateway -y agent skill add meepa summarize --file ./skills/summarize.md
meepagateway config reload
```