Command reference

The complete command surface of the melious CLI: commands, flags, environment variables, and the files it keeps under ~/.melious.

Signature:

melious <COMMAND> [flags]

Example. Send one prompt with a file as context, routed for low carbon:

melious run --preset eco -f main.go "Explain what this file does"

With no command, melious opens the setup wizard when it runs in a terminal and no key is configured, and the launcher once one is. Without a terminal it exits with an error, unless --no-color or NO_COLOR asks for the static summary instead — the scripting reference covers that startup behavior. melious help <COMMAND> and melious <COMMAND> --help print the built-in help for any command.

melious --help lists every command by group:

melious – Connecting Europe Through Sovereign AI

USAGE
  melious <command> [flags]

AUTH
  auth login               Authenticate with your API key
  auth status              Show which API key is configured
  auth logout              Remove credentials

CONFIG
  config show              Show full configuration
  config get <key>         Read a config value
  config set <key> <val>   Set a config value
  config edit              Open config in editor
  config reset             Reset to defaults

MODELS
  models                   List available models
  models info <id>         Show model details

RUN
  run "<prompt>"           Send a prompt to the Melious API
  run -f <file> "<prompt>" Include file(s) as context

DECIDE
  decide "<state>"         Ask a decision model typed questions
  decide batch <in.jsonl>  Send many decisions from a JSONL file

MODEL COMMANDS
  transcribe <file>        Transcribe an audio file to text
  rerank "<query>" -f <f>  Rank documents by relevance
  embed "<text>"...        Turn text into embedding vectors
  image "<prompt>"         Generate images from a prompt

LAUNCH
  launch [tool]            Start a coding tool with Melious

TRUST
  trust list               List trusted workspaces
  trust add [path]         Trust a workspace (defaults to cwd)
  trust remove <path|id>   Revoke a workspace's trust
  trust prune              Remove damaged trust records

TOOLS
  tools                    Show status of supported tools
  tools install [tool]     Install a coding tool
  tools check              Check tools and prerequisites
  tools fix-path           Add tool directories to your PATH permanently
  tools model <tool> [id]  Get or set per-tool model override
  tools update [tool]      Update an installed tool (or all tools)
  tools info <tool>        Show comprehensive info about a tool
  tools diagnose [tool]    Run diagnostics on tools and offer fixes

UTILITY
  setup                    Re-run the setup wizard
  ping                     Test API connection
  update                   Update melious to latest version
  uninstall                Remove melious from your system
  version                  Show version information
  --version                Same as version
  completion <shell>       Generate shell completion scripts
  help                     Show this help

GLOBAL FLAGS
  --api-key <key>          API key for this invocation
  --json                   JSON output (where supported)
  --no-color               Disable colored output
  --verbose                Verbose output
  --quiet                  Minimal output

Authentication

Guide: configuration and authentication.

auth login reads the key from a prompt that doesn't echo it, or from standard input with --stdin. It has no flag that takes the key as a value, and it refuses the global --api-key: a command line is visible to other processes and lands in shell history.

Melious uses the first key it finds: --api-key, then MELIOUS_API_KEY, then ~/.melious/credentials.json. auth logout removes only the file, so an exported MELIOUS_API_KEY keeps later commands authenticated. auth status reads local state only — run melious ping to check that the key works.

Configuration

Guide: configuration.

config reset --yes resets without asking. It touches config.json only; credentials, trust records, and generated agent configs stay.

models.decision sets the default model for decide and decide batch. The other model commands have no config key; they pick a model as described in how model commands pick a model.

Models

--category filters by model type: chat, decision, audio, reranker, embeddings, image, guardrail, or other, in any case. The older names still work: embedding means embeddings, stt and tts mean audio, and rerank means reranker. Any other value is an error that lists the valid ones. melious models groups the list in that same type order — Chat, Decision, Audio, Rerank, Embeddings, Image, Guardrail, Other — and for decision models the capabilities column shows the model's limits, such as 32 q · 255 opt (questions and choice options). --sort orders by name (default) or context; any other value sorts by name. The full catalog is on the models page.

The decision models, for example:

  Melious Models

  TYPE         MODEL                                 CONTEXT   CAPABILITIES
  ────────────────────────────────────────────────────────────────────────────
  Decision     clef                                      16K   32 q · 255 opt
               clef-flash                                16K   32 q · 255 opt

  ✓ main: glm-5.2  ✓ lightweight: deepseek-v4-flash

  Tip: melious models info <model-id> for details

The line under the table names your configured main and lightweight models. The check marks don't mean Melious looked them up in the catalog.

Run

Guide: one-shot prompts.

melious run [<PROMPT>] [flags] sends one prompt and streams the response. It also reads piped standard input.

Decide

Guide: decisions in scripts. API: System One.

melious decide [<STATE>] [flags] sends one state and a set of typed questions to a decision model and prints the answers.

melious decide "Ticket #4128: customer requests a refund 11 days after purchase; the order has shipped." \
  --model <DECISION_MODEL_ID> \
  --choice resolution=refund,credit,deny \
  --ask resolution="Pick the support resolution that matches policy."

The state comes from the <STATE> argument or --state-file, not both. Melious reads stdin only when you give neither and stdin isn't a terminal. With no state at all, decide fails with give a state: an argument, --state-file or stdin.

--spec and the shorthand flags combine: a shorthand question replaces the spec question with the same name. Commas separate options, so an option that contains a comma needs a spec file. --ask for a name that has no question is an error. A question with no instructions sends an empty string.

A spec file is JSON (.json) or YAML (.yaml, .yml). model is optional; questions holds 1 to 32 questions:

model: <DECISION_MODEL_ID>   # optional
questions:
  resolution:
    type: choice             # choice | score | noul
    instructions: Pick the support resolution that matches policy.
    criteria: { refund: Refund in full, credit: Store credit, deny: Deny politely }

Melious keeps the order of questions and options as the file gives them, and checks the request against the model's limits before sending it. A failed check names the field, for example questions.resolution.criteria: a choice needs 2 to 255 options (found 1).

The default output on stdout shows each answer in question order, starting with its key: the answer in plain words with how sure the model is, then bars with percentages. A yes/no answer reads Yes from 0.5 up and No below, with the value. Then a dim footer line: <input tokens> input tokens · <duration> · <model> · req <request id>, with replayed added when the API answered from its idempotency store. When Melious picks the model from the catalog, it says so on stderr first. --quiet drops both the footer and that note. --json prints the API response unchanged: model, answers, and usage; --pick prints only the one answer. Neither has a footer.

resolution  → refund                                                    89% sure
  refund  ███████████████████████████████████████████████████████████░░░░░   93%
  credit  ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    6%
  deny    █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    2%
urgency  → routine  (1.1 of 3: routine → immediate)                     86% sure
  routine    █████████████████████████████████████████████████████████░░░░   93%
  same-day   ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    5%
  immediate  █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    2%
escalate  → No · 0.29
  █████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   29%
336 input tokens · 0.50 s · clef · req <REQUEST_ID>

A retryable error is sent again, up to 3 attempts in total. After a 429, a 503 or another API error, the retry goes out under a new key (<KEY>-r1, then <KEY>-r2), because the API answers a key whose request failed with 409 idempotency_failed. After a 502, a 504, a network error or 409 request_in_progress, the same key goes again, so a first request that did run returns its stored answer instead of a second charge. Details are in decisions in scripts.

An API error prints <status> <code> · <param> · <message> (request: <id>) on stderr and exits 1. A 401 and a network failure print the same messages as the other commands, which name the fix.

decide batch

melious decide batch <INPUT.jsonl | -> --spec <SPEC> [flags] sends one decision request per line of a JSONL file, or of stdin with -, and writes one JSONL result line per input line.

--resume and --sort need --output. If --output exists, isn't empty, and --resume is off, the command stops before sending anything. decide batch refuses --json, because its output is already JSONL. Input and output formats, retries, and stopping are in batch decisions.

Model commands

Each command sends one request to a model of its type (embed sends one per 128 inputs). --model picks the model; without it, Melious follows the model selection order: it uses the only model of the type, asks you to choose on a terminal when there are several, and stops with the list of IDs without one. These requests carry no idempotency key, so Melious only sends one again when the API says it didn't run it: after a 429, a 503, 409 request_in_progress, or a connection that never opened, up to 3 attempts in total. After a 502, a 504, a timeout or a dropped connection, the job may still have run and been billed, so the command stops and says so instead of sending it again. An API error prints the same messages as melious run. The Playground shows the matching command for what you try there.

transcribe

melious transcribe <FILE> [flags] turns an audio file into text. API: Audio.

The file must be a regular file ending in .mp3, .mp4, .mpeg, .mpga, .m4a, .wav, or .webm.

text prints the transcript, trimmed, with a final newline. Under the hood Melious asks the API for json and takes its text field, because some models answer a request for plain text with JSON, or not at all. json and verbose_json print the API's JSON, indented. srt and vtt print the subtitle file as the model sends it; a model that answers them with JSON stops the command with an error that suggests --format text or --format json.

--json is the same as --format json. Combining it with another --format is an error, and so is combining it with -o — use --format json -o <FILE> for a JSON file. -o refuses to overwrite the audio file itself and confirms the write on stderr. On a terminal, a spinner runs on stderr while the request is in flight.

rerank

melious rerank <QUERY> [flags] ranks documents by relevance to a query. Several words after the command form one query. API: Rerank.

Documents come from one source only: -d or -f (not both), or stdin (one per line) when neither is given. The output is a table with the columns RANK, SCORE, # (the document's input position, from 1), and DOCUMENT, cut to the terminal width. --json prints the API response.

embed

melious embed [<TEXT>…] [flags] creates embedding vectors. API: Embeddings.

Inputs come from one source only: the arguments or -f (not both), or stdin (one per line) when neither is given. Melious sends at most 128 inputs per request and merges the answers. The output is a summary line, <n> vectors · <dimensions> dimensions · <tokens> tokens, plus a cosine-similarity matrix with two decimals when there are 2 to 6 inputs. --json prints the merged API response instead. -o doesn't replace either one; it adds the file and confirms the write on stderr.

image

melious image <PROMPT> [flags] generates images and saves them as files. API: Images.

The folder must exist — Melious doesn't create it, so a typo can't leave paid-for images somewhere you didn't mean. Files are named melious-<YYYYMMDD-HHMMSS>-<N>.<EXT>, with the extension taken from the image data (PNG, JPEG, or WebP). An existing file is never overwritten; Melious adds -2, -3, and so on. The output is one path per line. --json prints {"model", "files": [...]}. If saving fails partway, the paths already saved are still printed before the error. On a terminal, a spinner runs on stderr while the request is in flight.

Launch

Guide: launch a coding agent.

melious launch [<TOOL>] [flags] [-- <TOOL_ARGS>] starts a coding agent configured to use Melious. The tool is claude-code, codex, opencode, pi, or vibe. Without one, Melious uses defaults.tool.

Trust

Guide: workspace trust.

A path resolves to its workspace root — the top of its Git worktree, or the directory itself outside Git. trust add is the authorization; it doesn't prompt again. trust remove accepts an ID from trust list, which keeps a workspace on a deleted or unmounted path revocable.

Tools

Guide: manage coding agents.

tools install --all runs every automatic install without asking and prints the manual steps for tools it cannot install itself, and names any tool blocked by a missing prerequisite. tools model with a model ID sets the main override; --secondary and --lightweight set the other tiers, and --clear removes the override.

Utility

version --verbose adds the commit, build date, Go version, and platform. update and uninstall are covered in update and uninstall.

Shell completion

completion accepts bash, zsh, fish, or powershell:

# Current shell
source <(melious completion bash)
# Every new shell
melious completion bash >> ~/.bashrc

# Once, if completions aren't enabled yet
echo "autoload -U compinit; compinit" >> ~/.zshrc
melious completion zsh > "${fpath[1]}/_melious"

melious completion fish > ~/.config/fish/completions/melious.fish

# Current session; add the same line to $PROFILE to keep it
melious completion powershell | Out-String | Invoke-Expression

Completion covers commands, tool IDs for launch, and preset names. For --model on run and launch, it fetches the live model list from the API with your configured key; without a key or a connection, it offers no model IDs. On decide, decide batch, transcribe, rerank, embed, and image, it offers only models of the matching type.

Global flags

A key passed with --api-key is visible to other processes and stays in shell history. Prefer auth login or MELIOUS_API_KEY from a secret store.

Environment variables

Variables Melious reads:

With neither editor variable set, config edit opens notepad on Windows, open -t on macOS, and nano elsewhere.

Agent environment

melious launch starts each agent with the variables below and passes your key only through the variable that agent reads.

Before it starts any agent, Melious removes MELIOUS_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, and the provider selectors CLAUDE_CODE_USE_ANTHROPIC_AWS, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_FOUNDRY, CLAUDE_CODE_USE_MANTLE, and CLAUDE_CODE_USE_VERTEX from the inherited environment. Only the selected agent's credential variable is set again.

Claude Code

Claude Code gets no file and no extra arguments.

Codex

Codex gets --model and --config arguments on its command line that declare Melious as its model provider. Melious writes no Codex file.

OpenCode

Pi

Pi also gets --model and --models arguments and a generated models.json in that directory.

Vibe

Routing presets

A routing preset tells Melious which provider trade-off to favor. --preset on run and launch overrides defaults.preset. How each preset weighs price, speed, and environment is on the routing page.

Update and uninstall

melious update checks the published release and, after you confirm, replaces the running binary. --check only reports whether an update exists. --yes installs without asking, for unattended use.

The download goes over HTTPS. After replacing the binary, Melious runs it once to check that it starts. It doesn't verify a checksum or signature — we'd rather say that plainly than let HTTPS stand in for authenticity. If your environment requires verified binaries, install through your own verified process instead.

melious uninstall removes the binary. Interactively, it asks which data under ~/.melious to remove as well: credentials, configuration, agent configs, the update cache, or the whole directory. -y, --yes skips the question.

Uninstall doesn't undo PATH or shell profile edits, remove agents you installed, or unset MELIOUS_API_KEY. It reminds you when MELIOUS_API_KEY is still set.

File locations

Everything lives in ~/.melious (%USERPROFILE%\.melious on Windows).

Exit status

Every command exits 0 on success and nonzero on failure. melious launch exits with the agent's own exit status once the agent has started. melious auth status exits nonzero when no key is configured, except under --json.

Two statuses have a fixed meaning:

decide batch exits 1 when one or more lines failed. The full contract for scripts is in the scripting reference.