Configuration

How the melious CLI finds your API key, and what lives in ~/.melious/config.json.

Signature:

melious auth login | status | logout
melious config show | get <KEY> | set <KEY> <VALUE> | edit | reset

Example. Sign in with the hidden prompt, then make opencode the agent melious launch starts with no argument:

melious auth login
melious config set defaults.tool opencode

For the API-side picture of keys and scopes, see Authentication.

Authentication

Log in

melious auth login

Melious prints where to get a key (melious.ai/account/api/keys) and asks for it on a prompt that doesn't echo what you type. It checks the key against the API before writing anything, so a typo fails here and never reaches the file.

The prompt needs a real terminal. Without one, or with TERM=dumb, auth login exits with an error that points you to --stdin.

Log in from a secret source

--stdin reads the key from standard input instead. Feed it from a file only you can read, or from your password manager's command-line tool:

melious auth login --stdin < <PATH_TO_KEY_FILE>

The input must be one line (at most 4 KiB) starting with sk-mel-. Surrounding whitespace, including the trailing newline most tools add, is trimmed. Anything else — an empty pipe, two lines, a missing prefix — is refused before Melious contacts the API.

auth login refuses --api-key with an error. We refuse it on purpose: a key in the command line is visible to other processes on the machine and lands in your shell history. For CI, where you usually don't want a stored file at all, see safe credentials in CI.

Which key Melious uses

Every command takes the first key it finds:

The --api-key flag, for that one invocation
The MELIOUS_API_KEY environment variable
The stored credentials file, ~/.melious/credentials.json

--api-key has the same visibility problem as above, so prefer the environment variable when you need to override the stored key. If MELIOUS_API_KEY is set when you log in or out, Melious warns you that it outranks the file.

Check the key

melious auth status
melious ping

auth status is offline: it reports which key is configured and where it came from, and it doesn't check that the key works. It exits nonzero when no key is configured. With a stored key (mask shortened):

  ✓ API key configured via the credentials file

    Key:   sk-mel-****************1234
    Since: 2026-09-10 11:45 UTC
    File:  ~/.melious/credentials.json

  → Configured, not verified. Check the key works with: melious ping

ping contacts the API and tells you whether the key connects:

  ✓ Connected to api.melious.ai
    Latency:  90ms
    Models:   54 available
    Key:      sk-mel-****************1234
    Preset:   balanced

Log out

melious auth logout

This deletes ~/.melious/credentials.json, plus any leftover temporary copy of it from an interrupted login, and nothing else. An exported MELIOUS_API_KEY isn't Melious's to remove, so later commands stay authenticated until you unset MELIOUS_API_KEY.

How the key is stored

Plaintext credentials

The credentials file is plaintext JSON. Melious doesn't encrypt it and doesn't use an OS keychain. Every agent you start with melious launch also receives the key, under the variable that agent reads (for example ANTHROPIC_AUTH_TOKEN for Claude Code). Anything that agent runs as you can read it.

On Unix the file is written with mode 0600. If any group or other permission bit is set, Melious refuses to read it and prints the chmod 600 command that fixes it. On Windows, protection comes from the file sitting in your per-user profile directory; Melious sets no extra access controls there.

Config file

Settings live in ~/.melious/config.json, a JSON object. The file holds only the keys you've set — config set writes one key at a time and leaves everything else in the file alone.

Where defaults come from

Each value resolves from three layers, highest first:

Your overrides — keys present in config.json
Remote defaults — a small defaults file Melious downloads, caches in ~/.melious/defaults-cache.json, and refreshes at most every four hours, after a command finishes. auth and trust commands, and runs with --json or --quiet, don't refresh it
Compiled defaults — built into the binary

Remote defaults can change models.main, models.secondary, models.lightweight, defaults.tool, and defaults.preset without a CLI release. We did it that way so a better default model reaches you without an update. It also means the compiled values below aren't a promise: config show is the source of truth for what your install uses right now, and it labels those five values as (default), (remote), or (your override). A value you set always wins, and it stops following remote changes.

Config keys

Defaults are the compiled ones. Remote defaults can replace models.main, models.secondary, models.lightweight, defaults.tool, and defaults.preset. models.decision isn't one of them: it's empty until you set it, and config show lists it as not set.

Key	Type	Default	What it does
`models.main`	text	`glm-5.2`	Main model for `run` and launched agents
`models.secondary`	text	`minimax-m3`	Middle tier, for agents that use one
`models.lightweight`	text	`deepseek-v4-flash`	Small, fast tier, for agents that use one
`models.decision`	text	empty	Decision model for `decide` and `decide batch`
`defaults.tool`	text	`claude-code`	Agent `melious launch` starts with no argument
`defaults.preset`	text	`balanced`	`balanced`, `speed`, `price`, or `eco`
`run.system_prompt`	text	empty	System prompt for `melious run`
`run.temperature`	number, 0–2	`0.7`	Sampling temperature for `melious run`
`run.max_tokens`	whole number	`4096`	Completion length cap for `melious run`
`run.stream`	`true` / `false`	`true`	Stream `melious run` output as it arrives
`autoupdate`	`true` / `false`	`true`	Show an "update available" notice after commands

autoupdate only controls the notice. Melious never installs an update on its own — that takes melious update.

The routing presets are described in Routing. Which tiers each agent uses is on Launch a coding agent.

Per-agent models

tool_models.<TOOL>.main, tool_models.<TOOL>.secondary, and tool_models.<TOOL>.lightweight override models.* for one agent. They're unset by default. When you launch, flags such as --model win over these, and these win over models.*.

melious config set tool_models.opencode.main <MODEL_ID>

melious tools model writes the same keys, and it rejects an unknown agent name. config set doesn't check the agent name — see Manage coding agents.

How model commands pick a model

melious decide, decide batch, transcribe, rerank, embed, and image each need a model of one type. They take the first answer from this list:

The --model flag.
For decisions only: the model field of the spec.
For decisions only: the models.decision key.
The catalog, when your key can use exactly one model of that type. Melious uses it and says so on stderr, for example: Using clef, the only decision model. Set models.decision to choose a different one. --quiet hides the note.
When your key can use two or more models of that type, Melious asks you to choose one when stdin and stderr are terminals. The question names the way to skip it next time: --model, and for decisions also models.decision. Without a terminal, it stops with more than one <type> model is available (<IDS>); choose one with --model.
When your key can use no model of that type, it stops with no <type> models are available for this API key.

<type> is decision, transcription, rerank, embeddings, or image. Melious doesn't check a model you name in steps 1 to 3 against the catalog; a wrong ID comes back as an API error.

Step 4 is a convenience, not a promise: the day a second decision model appears on your account, an unpinned script stops at step 5. Pin the model in scripts:

melious config set models.decision <DECISION_MODEL_ID>

You can also set it in the terminal UI, under Settings › Default decision model, where x clears it. melious config set models.decision "" clears it from the command line. Only decisions have a config key; for the other model commands, pass --model. No model key has an environment variable.

Config commands

Show everything

melious config show

Prints the resolved settings (models, defaults, run, and autoupdate), with the source label on the values remote defaults can change. Per-agent tool_models overrides appear only with --json, which prints one JSON object.

On a fresh install, before you've set anything:

  Melious Configuration

  File: ~/.melious/config.json
  ────────────────────────────────────────────────────────────────────────────

  MODELS
    main:         glm-5.2 (default)
    secondary:    minimax-m3 (default)
    lightweight:  deepseek-v4-flash (default)
    decision:     not set

  DEFAULTS
    tool:         claude-code (default)
    preset:       balanced (default)

  RUN
    temperature:  0.7
    max_tokens:   4096
    stream:       true

  autoupdate:     true

  Tip: melious config set <key> <value> → e.g. melious config set models.main deepseek-r1-0528

Read one key

melious config get models.main

Keys use the dot paths from config keys. An unknown key, including a retired one, fails with unknown config key. So does a tool_models.<TOOL>.<TIER> key that isn't set.

Set one key

melious config set run.stream false

config set checks the value before writing and leaves the file untouched if it's refused:

Unknown keys, and group names such as models on their own, are refused.
true/false keys take exactly true or false.
run.max_tokens takes a whole number, and run.temperature a number from 0 to 2.
Text keys take any text. Melious doesn't check that a model, agent, or preset name exists, so a typo shows up at the next run or launch.

Open in your editor

melious config edit

Melious opens $VISUAL, then $EDITOR. With neither set, it uses notepad on Windows, open -t on macOS, and nano elsewhere — we'd rather a new user find their way out of the editor than guess at their muscle memory. If the file doesn't exist yet, Melious creates it as {} first.

Reset to defaults

melious config reset

Asks for confirmation, then replaces config.json with {}. Add --yes to skip the question — without a terminal, config reset refuses to run unless you do.

Reset touches config.json only. Your credentials, trust records, and generated agent configs stay. It does drop every key in the file, including retired and unknown ones.

Fix a broken config

If config.json isn't valid JSON or holds a wrong-typed value, config show and config get fail and print the remedy. Commands that read settings warn and carry on with the compiled defaults, without the remote layer.

Wrong type at a settable key — overwrite it: melious config set <KEY> <VALUE>.
Not valid JSON, or the top-level value isn't an object — config set can't parse the file either. Fix it with melious config edit, or start over with melious config reset.
Wrong type in a nested object, for example "models": "x" — config show and config get fail, but config set can still write the file: melious config set models.main <MODEL_ID> replaces the bad value. config edit and config reset also work.

Retired keys

The image.*, diff.*, stats.*, and output.* keys belong to commands and output options removed in v0.2.0. If your file still has them, Melious ignores them: they don't appear in config show, config get and config set call them unknown, and config set on other keys leaves them in the file. There's nothing you need to clean up. For color, use --no-color or NO_COLOR; the CLI's own text is English only. What replaced each removed command is on the migration page.

On this page