CLI Reference

The mvgc CLI is the recommended interactive tool for managing Axemere Gateway. It wraps every operation available through the Admin API. For direct HTTP access or scripting without the CLI, see the Admin API Reference. For automating a managed gateway from CI/CD or IaC with an API key instead of a gateway admin token, see the Management API Reference, or the MCP Server Reference to drive the same operations from an AI assistant.

Installation
Configuration
Global flags
Commands
- version
- health
- config
- credentials
- workloads
- policies
- approvals
- quarantine
- ratelimit
- connectors
- nodes
- records
Common patterns

Installation

The mvgc binary is built from cmd/mvgc/:

make build-cli
# or
go build -o mvgc ./cmd/mvgc

It is also included in the Homebrew formula, deb/rpm packages, and the official container images under /usr/local/bin/mvgc.

Configuration

The CLI resolves connection settings from the following sources, highest priority first:

Priority	Source	Keys
1	`--url` / `--token` flags	per-invocation
2	Environment variables	`MVGC_GATEWAY_URL`, `MVGC_ADMIN_TOKEN`
3	User config file	`~/.config/mvgc/config.yaml`
4	System config file	`/etc/mvgc/mvgc.yaml` (reads `gateway.admin_token` and `gateway_url`)

User config file (~/.config/mvgc/config.yaml):

gateway_url: http://localhost:7080
admin_token: secret-token
output: table   # table | json | yaml

Use mvgc config subcommands to manage this file without editing it directly.

System config fallback: On hosts where the gateway is installed, the CLI can read /etc/mvgc/mvgc.yaml directly. If gateway_url is not set there but gateway.listen_addr is (e.g. :7080), the CLI derives http://localhost:7080 automatically.

Global flags

These flags may appear before the subcommand name:

Flag	Description
`--url <url>`	Gateway URL (overrides config and env)
`--token <token>`	Admin token (overrides config and env)
`--output <fmt>`	Output format: `table` (default), `json`, `yaml`
`--help` / `-h`	Show help

Output formats:

table -- Human-readable aligned columns; the default for interactive use.
json -- Machine-readable JSON; useful for jq pipelines and scripting.
yaml -- YAML output; useful for round-tripping into config files.

Commands

version

mvgc version

Prints the CLI version string. No gateway connection required.

health

mvgc health

Checks gateway health. Does not require an admin token. Returns status, version, node ID, control plane connection status, and connector health.

config

Manages the user config file at ~/.config/mvgc/config.yaml.

Subcommand	Description
`config show`	Show current effective configuration (token is masked)
`config set-url <url>`	Persist the gateway URL to the user config file
`config set-token <token>`	Persist the admin token to the user config file

mvgc config set-url http://gateway.internal:7080
mvgc config set-token my-admin-token
mvgc config show

credentials

Manage API credentials registered with the gateway. Credentials are used by the policy DSL to inject provider API keys without exposing them to callers.

Subcommand	Description
`credentials list`	List all registered credentials
`credentials get <id>`	Show detail for a single credential
`credentials create --file <path>`	Register a credential from a JSON or YAML file
`credentials update <id> --file <path>`	Update an existing credential from a file
`credentials delete <id>`	Delete a credential
`credentials reload`	Re-read all `*.yaml` files from `MVGC_CREDENTIALS_DIR` and upsert

Example credential file (cred-openai.yaml):

credential_id: cred-openai
provider: openai
mode: alias
billing_owner: customer
secret_ref: OPENAI_API_KEY
org_id: org-example-001
connector_id: openai
scopes:
  - chat
  - embeddings

mvgc credentials create --file cred-openai.yaml
mvgc credentials list
mvgc credentials get cred-openai
mvgc credentials delete cred-openai
mvgc credentials reload

See Credential Configuration in the Network Operations Guide for field descriptions.

workloads

Manage workload identities. Workloads represent applications or services that submit requests through the gateway.

Subcommand	Description
`workloads list`	List all registered workloads
`workloads get <id>`	Show detail for a single workload
`workloads create --file <path>`	Register a workload from a JSON or YAML file
`workloads update <id> --file <path>`	Update an existing workload from a file
`workloads delete <id>`	Delete a workload

Example workload file (wl-prod-app.yaml):

workload_id: wl-prod-app-1
org_id: org-example-001
name: Production Application
default_attribution:
  customer_id: cust-default
  account_id: acct-default
allowed_connection_types:
  - direct_api

mvgc workloads create --file wl-prod-app.yaml
mvgc workloads list
mvgc workloads get wl-prod-app-1
mvgc workloads delete wl-prod-app-1

policies

Manage the active policy bundle on the gateway.

Subcommand	Description
`policies get`	Show the currently active bundle (`bundle_id`, `version`, `source`, `loaded_at`)
`policies push --file <path>`	Hot-load a YAML policy bundle without restarting
`policies reload`	Reload `bundle.yaml` and all add-ons from `MVGC_POLICIES_DIR` on disk

mvgc policies get
mvgc policies push --file configs/examples/mvp_policy.yaml
mvgc policies reload

source in the get output is one of:

override -- bundle was hot-loaded via push
file -- loaded from disk (after reload or on startup)
default -- built-in deny-all fallback (no bundle configured)

See Policy Configuration in the Network Operations Guide for bundle format and hot-loading details.

approvals

Manage approval requests created when a policy rule returns require_approval.

Subcommand	Flags	Description
`approvals list`	`--status <s>`, `--org-id <id>`, `--limit <n>`	List approval requests
`approvals get <id>`		Show a single approval request
`approvals approve <id>`	`--decided-by <name>`	Approve a pending request
`approvals deny <id>`	`--decided-by <name>`	Deny a pending request

Status values: pending, approved, denied, expired.

mvgc approvals list --status pending
mvgc approvals get a1b2c3d4-...
mvgc approvals approve a1b2c3d4-... --decided-by ops-admin
mvgc approvals deny   a1b2c3d4-... --decided-by ops-admin

See Approval Workflows for the full lifecycle.

quarantine

Review and release quarantined requests.

Subcommand	Flags	Description
`quarantine list`	`--org-id <id>`, `--limit <n>`	List quarantine entries
`quarantine release <id>`	`--decided-by <name>`	Release a quarantined entry

mvgc quarantine list --org-id org-example-001
mvgc quarantine release q9z8y7x6-... --decided-by ops-admin

See Quarantine Management for the full lifecycle and policy integration.

ratelimit

Inspect and adjust the gateway's token bucket rate limiter at runtime.

Subcommand	Flags	Description
`ratelimit config get`		Show current rate limiter configuration
`ratelimit config set`	`--refill-rate <n>`, `--max-tokens <n>`	Update rate limiter parameters
`ratelimit keys`		List workload IDs with active rate limit state

Both --refill-rate and --max-tokens must be greater than 0. Changes take effect immediately without a restart.

mvgc ratelimit config get
mvgc ratelimit config set --refill-rate 20 --max-tokens 50
mvgc ratelimit keys

See Rate Limiting for policy integration and configuration details.

connectors

mvgc connectors list

Lists registered connectors with ID, version, and health status. Connector health reflects configuration state (credential availability), not a live ping to the upstream provider.

See Connector Management for details on connector routing and health interpretation.

nodes

mvgc nodes list

Lists registered gateway nodes. The mode field is embedded (standalone) or distributed (connected to the control plane via gRPC).

records

mvgc records verify <record_hash>

Verifies a record's Merkle inclusion proof. Returns status: verified (with proof details) or status: pending_inclusion (record exists but has not yet been included in a Merkle batch). Use --output json for the full proof structure.

mvgc records verify sha256:abc123...
mvgc --output json records verify sha256:abc123... | jq .

Common patterns

Script-friendly output with jq:

# List credential IDs only
mvgc --output json credentials list | jq -r '.[].credential_id'

# Count pending approvals
mvgc --output json approvals list --status pending | jq '.items | length'

# Check if a specific workload exists
mvgc --output json workloads list | jq -r '.[] | select(.workload_id == "wl-prod-app-1")'

Connecting to a non-default gateway:

mvgc --url http://gateway.prod:7080 --token prod-token policies get

Piping a bundle from stdin via curl then verifying with mvgc:

# Push via curl (bundle with inline content)
curl -X PUT http://localhost:7080/v1/admin/policies \
  -H "MVGC-Admin-Token: $MVGC_ADMIN_TOKEN" \
  -H "Content-Type: application/yaml" \
  --data-binary @bundle.yaml

# Verify the result with mvgc
mvgc policies get