CLI Reference

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:

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.

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.

meepagateway setup

`stop`

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

meepagateway stop

`restart`

Stop and re-launch with the same arguments.

meepagateway restart

`status`

Show gateway status. No authentication required.

meepagateway status
meepagateway status --json

`update`

Check for updates and self-update the binary.

meepagateway update           # download and install latest
meepagateway update --check   # check without installing

`uninstall`

Remove the binary and skills catalog.

meepagateway uninstall          # binary only
meepagateway uninstall --purge  # also removes ~/.meepagateway/ agent data

Config commands

`config show`

Show current configuration (secrets redacted).

meepagateway config show
meepagateway config show --json

`config raw`

Show the raw config file contents.

meepagateway config raw

`config edit`

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

meepagateway config edit

`config validate`

Validate config without saving.

meepagateway config validate
meepagateway config validate --file ./config.yaml

`config reload`

Reload config from disk.

meepagateway config reload

`config reset`

Reset config to defaults (preserves authentication settings).

meepagateway config reset

Agent commands

`agent list`

List all agents.

meepagateway agent list
meepagateway agent list --json

`agent show [ID]`

Show details for an agent.

meepagateway agent show meepa

`agent create`

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

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.

meepagateway agent update meepa --model claude-opus-4-6 --max-iterations 20

`agent delete [ID]`

Delete an agent.

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

meepagateway agent soul show meepa

`agent soul edit [ID]`

Open soul in $EDITOR.

meepagateway agent soul edit meepa

`agent soul set [ID]`

Set soul from a local file.

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).

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).

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.

meepagateway agent skill list meepa

`agent skill show [ID] <NAME>`

Show a skill’s content.

meepagateway agent skill show meepa summarize

`agent skill add [ID] <NAME>`

Add or update a skill from a file.

meepagateway agent skill add meepa summarize --file ./skills/summarize.md

`agent skill remove [ID] <NAME>`

Remove a skill.

meepagateway agent skill remove meepa summarize

`agent skill catalog`

List skills available in the bundled catalog.

meepagateway agent skill catalog

`agent skill install [ID] <NAME>`

Install a skill from the bundled catalog.

meepagateway agent skill install meepa web-search

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

Install a skill from a GitHub repository.

meepagateway agent skill install-url meepa owner/repo

Connector commands

`agent connector list [ID]`

List connectors for an agent.

meepagateway agent connector list meepa

`agent connector add [ID]`

Add a connector. Run without flags for interactive mode.

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.

meepagateway agent connector edit meepa discord

`agent connector remove [ID] <NAME>`

Remove a connector.

meepagateway agent connector remove meepa discord

`agent connector test`

Test a connector connection without saving.

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.

meepagateway agent mcp meepa

Cron commands

`agent cron list [ID]`

List cron jobs for an agent.

meepagateway agent cron list meepa

`agent cron show [ID] [JOB_ID]`

Show cron job details.

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.

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

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.

meepagateway agent cron delete meepa <job-id>

`agent cron run [ID] [JOB_ID]`

Trigger a cron job immediately.

meepagateway agent cron run meepa <job-id>

Credentials and secrets commands

`agent credentials [ID]`

Launch the interactive credentials setup wizard for an agent.

meepagateway agent credentials meepa

`agent secrets [ID]`

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

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.

meepagateway secrets list

`secrets set/get/remove`

Manage gateway-level secrets.

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.

meepagateway api-key list

`api-key create <NAME>`

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

meepagateway api-key create "ci-deploy"

`api-key revoke <ID>`

Revoke an API key.

meepagateway api-key revoke <id>

Container commands

`container status`

Show container mode configuration and image status.

meepagateway container status

`container build`

Build the container image.

meepagateway container build
meepagateway container build --force

`container list`

List container images.

meepagateway container list

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

Remove a specific image or all container images.

meepagateway container remove v1
meepagateway container clean

Webhook commands

`webhook setup`

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

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.

meepagateway webhook status

`webhook enable` / `webhook disable`

meepagateway webhook enable
meepagateway webhook disable

Tips

JSON output for scripting:

meepagateway --json agent list | jq '.[].id'

Remote management:

export MEEPA_URL="https://gateway.example.com"
export MEEPA_API_KEY="cptn_..."
meepagateway agent list

Non-interactive for CI/CD:

meepagateway -y agent skill add meepa summarize --file ./skills/summarize.md
meepagateway config reload

​Global flags

​Authentication

​Interactive mode

​Server commands

​start

​setup

​stop

​restart

​status

​update

​uninstall

​Config commands

​config show

​config raw

​config edit

​config validate

​config reload

​config reset

​Agent commands

​agent list

​agent show [ID]

​agent create

​agent update [ID]

​agent delete [ID]

​Soul commands

​agent soul show [ID]

​agent soul edit [ID]

​agent soul set [ID]

​Memory and user profile commands

​agent memory show/edit/set [ID]

​agent user show/edit/set [ID]

​Skill commands

​agent skill list [ID]

​agent skill show [ID] <NAME>

​agent skill add [ID] <NAME>

​agent skill remove [ID] <NAME>

​agent skill catalog

​agent skill install [ID] <NAME>

​agent skill install-url [ID] <URL>

​Connector commands

​agent connector list [ID]

​agent connector add [ID]

​agent connector edit [ID] [NAME]

​agent connector remove [ID] <NAME>

​agent connector test

​MCP command

​agent mcp [ID]

​Cron commands

​agent cron list [ID]

​agent cron show [ID] [JOB_ID]

​agent cron create [ID]

​agent cron update [ID] [JOB_ID]

​agent cron delete [ID] [JOB_ID]

​agent cron run [ID] [JOB_ID]

​Credentials and secrets commands

​agent credentials [ID]

​agent secrets [ID]

​secrets list

​secrets set/get/remove

​API key commands

​api-key list

​api-key create <NAME>

​api-key revoke <ID>

​Container commands

​container status

​container build

​container list

​container remove <TAG> / container clean

​Webhook commands

​webhook setup

​webhook status

​webhook enable / webhook disable

​Tips