CLI commands

The merido binary is the entry point for running the gateway and managing its data. Run merido <command> --help for full details on any command. Examples below use cargo run -p merido -- for a source checkout; a built binary is just merido.

Running merido with no command opens the interactive menu when stdin is a TTY, and prints this help otherwise (so CI and piped scripts are unaffected).

start

Start the gateway (OpenAI-compatible API + dashboard).

merido start
merido start --port 9000        # also settable via MERIDO_PORT

Flag	Purpose
--port <u16>	Override the listen port (env: MERIDO_PORT).

keys

Manage client (gateway) API keys — what callers use to authenticate to merido.

merido keys create --name "my-laptop"
merido keys create --name "ci" --ttl-seconds 86400

Subcommand	Flags	Purpose
keys create	--name <str>, --ttl-seconds <i64>	Create a key (shown once). Omit TTL for a non-expiring key.
keys rotate	--org <i64>	Rotate the secrets-vault DEK and re-seal secrets. Omit --org for the system DEK.
keys status	--org <i64>	Show vault status (backend, active DEK version, KMS health).

providers

Manage upstream provider connections (API-key based).

merido providers add --provider openai --api-key sk-...
merido providers add --provider openrouter --api-key sk-... --label "personal" --base-url https://openrouter.ai/api/v1

Subcommand	Flags	Purpose
providers add	--provider <str> (required), --api-key <str> (required), --base-url <str>, --label <str>	Add a connection. Base URL defaults to the provider's known endpoint.

login <provider>

Sign in to an OAuth provider (browser PKCE for Claude/Codex/xAI, device-code for GitHub Copilot/Kiro). Captured tokens are stored encrypted at rest.

merido login claude
merido login claude --server https://your-gateway.example --token <gateway-key>

Argument / flag	Purpose
<provider>	Provider id, e.g. claude, codex, xai, github-copilot, kiro.
--server <url>	Upload the tokens to a remote gateway instead of the local store (env: MERIDO_SERVER).
--token <key>	Gateway API key authorizing the upload; required with --server (env: MERIDO_API_KEY).

accounts

Manage connected OAuth accounts.

merido accounts list
merido accounts remove 3

Subcommand	Purpose
accounts list	List connected OAuth accounts.
accounts remove <id>	Remove an account by id.

gain

Show usage totals and estimated cost.

merido gain

advise

Show current Token-Optimization Advisor recommendations.

merido advise

discover

Retrospectively scan recorded usage: total spend, per-source breakdown, spend anomalies (days that spiked 3×+ over their trailing baseline), and the top missed savings.

merido discover

menu

Open the interactive menu — a lightweight, non-fullscreen front-door that lets you pick a common action (start the server, create a key, add a provider, sign in, list accounts, show gain/advise, check for updates) and dispatches to the same handlers as the subcommands above. Equivalent to running merido with no arguments on a TTY. When stdin is not a TTY, it prints help instead, so scripts and CI are unaffected.

merido menu
merido            # same thing, when run in a terminal

update

Update merido in place to the latest GitHub release for your platform. It checks the latest release, compares it to the running version, and — if newer — downloads the matching OS/arch asset and atomically replaces the running binary. Restart merido afterwards to use the new version.

merido update
merido update --check   # only report whether a newer version exists

Flag	Purpose
--check	Only check for a newer version; download/replace nothing.

hash-password

Hash a dashboard password (argon2) and print the env var to set for MERIDO_DASHBOARD_PASSWORD_HASH.

merido hash-password --password 'a-strong-password'

Flag	Purpose
--password <str>	The plaintext password to hash.

import helicone

Import a Helicone configuration/export and create the equivalent merido provider connections. Idempotent — re-running skips connections that already exist.

merido import helicone --file ./helicone-export.json

Flag	Purpose
--file <path>	Path to the Helicone export/config JSON.

migrate

Move data between storage backends (SQLite ⇄ Postgres) — the "start on SQLite, graduate to Postgres" path. Copies orgs, users, connections, OAuth tokens, and virtual models in a foreign-key-safe order. Idempotent and resumable.

merido migrate --from ~/.merido/merido.db --to postgres://user:pass@host/merido
merido migrate --from ... --to ... --dry-run
merido migrate --from ... --to ... --only orgs,users,connections --resume

Flag	Purpose
--from <dsn>	Source DSN (SQLite path/URL or postgres://…).
--to <dsn>	Target DSN.
--dry-run	Plan only; write nothing.
--only <list>	Restrict to a comma-separated subset of entities.
--resume	Resume a prior run via the <to>.migrate.json checkpoint.

Encrypted secrets are copied as opaque ciphertext — decrypting them on the target requires the same MERIDO_MASTER_KEY as the source.