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.

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

A global --context <name> flag selects a saved server context (or local) for a single command, without changing the persisted active context — see server and Remote servers.

Not every command can act on a remote. What each does under --context <remote>:

Commands	Under a remote context
keys list, providers list, accounts list, gain	run against the remote's /api/*
keys create/rotate/remove, providers add/remove, accounts remove, advise, discover, login, import	refused with a message — they read or write the LOCAL store, and silently doing that while you believe you are on the remote is worse than an error
start, server, menu, tray, update, hash-password, migrate, doctor, setup	act on this machine; a context is not involved

login --server <url> --token <key> uploads captured OAuth tokens to a remote gateway. That is a separate mechanism from --context and works regardless of the active context.

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 list	—	List API keys on the active context.
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 list	—	List provider connections on the active context.
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. Three flow kinds across 11 providers: browser PKCE (claude, codex, xai, gitlab), device-code (github-copilot, kiro, qwen, kimi-coding), and vendor-custom (kilocode, cline, codebuddy). Run merido login <bad-id> to print the live roster from the registry. 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, gitlab, github-copilot, kiro, qwen, kimi-coding, kilocode, cline, codebuddy.
--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.

server

Connect to and switch between merido servers (local or a remote control plane, authenticated by an mdm_… management token). See Remote servers for the full workflow.

merido server add prod --url https://merido.dev --token mdm_xxxxxxxx
merido server use prod
merido keys list        # now runs against the remote context
merido server use local # back to this machine

Subcommand	Flags	Purpose
server add <name>	--url <url> (required), --token <mdm_…>	Add (or replace) a remote server and validate its token. Omit --token to be prompted.
server list (alias ls)	—	List configured servers and show the active one.
server use <name>	—	Switch the active context to <name> (or local).
server remove <name> (alias rm)	—	Remove a configured server.
server current	—	Show the active context and ping it.

Read commands (keys list, providers list, accounts list, gain) run against the active context; mutating commands and start always run locally for now.

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

doctor

Diagnose the local install — data dir, database, providers, keys, and port. Exits non-zero if any check FAILs, so it doubles as a health check in scripts.

merido doctor

setup

Print the environment a coding CLI needs to point at this merido — nothing is written to disk.

merido setup                 # generic (both Claude + OpenAI env)
merido setup claude          # Anthropic-style env
merido setup codex --url http://127.0.0.1:8788 --api-key md-...

Argument / flag	Purpose
<tool>	Which client: claude, codex/openai, or generic (default, prints both).
--url <url>	Base URL to advertise (default http://<host>:<port> from config).
--api-key <key>	API key to embed (default an md-... placeholder to fill in).

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

tray

Run a native system-tray icon (status + open-dashboard / quit). Only available in a build with --features tray on a desktop host; the default build prints how to enable it. The tray does not start the server — run merido start separately.

merido tray

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.