Terminal UI

Run melious with no command in a terminal and it opens a full-screen interface. Which screen you see depends on whether an API key is set. The same choices are also available as commands; each section below names them.

The interface needs a terminal. Without one, bare melious and setup refuse to run and name the alternatives. See scripting.

Setup wizard

If no key is configured, melious opens the setup wizard. You can also run it again any time with melious setup.

Welcome. Choose Start Setup or Exit.
Step 1: connect your account. Paste your API key into the text field. Three options sit below it: the text field, Get your Melious API key (opens the key page in your browser), and Next. Leave the field empty and press enter to keep the current key when you re-run setup. The wizard checks the key before going on.
Step 2: choose a default tool. The wizard lists the agents it found on your machine. Pick one; it becomes defaults.tool, the agent melious launch starts with no argument.
Done. A summary shows the connection, how many models your account can use, and the default tool.

If no agents are detected, the wizard skips step 2.

The welcome screen, with the animated logo cut from the top of the box:

╭─── melious setup ────────────────────────────────────────────╮
│                                                              │
│  …                                                           │
│                                                              │
│            Connecting Europe Through Sovereign AI            │
│                                                              │
│  Let's get you set up in a few quick steps.                  │
│                                                              │
│  Step 1 · Connect your Melious account                       │
│  Step 2 · Choose your default coding tool                    │
│                                                              │
│  ● Start Setup                                               │
│  ○ Exit                                                      │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
  ↑↓ navigate  ·  enter select  ·  q quit

Step 1 before you paste anything. The key shows as asterisks once you do:

╭─── melious setup · Step 1 of 2 ──────────────────────────────╮
│                                                              │
│  ◆ Connect your Melious account                              │
│                                                              │
│  Enter your Melious API key below.                           │
│                                                              │
│  ❯ sk-mel-...                                                │
│                                                              │
│  ○ Get your Melious API key                                  │
│  ○ Next                                                      │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
  ↑↓ navigate  ·  enter select  ·  ctrl+u clear input  ·  esc back

Step 2 lists the agents it found, each with a short description. Here it found four of the five:

╭─── melious setup · Step 2 of 2 ──────────────────────────────╮
│                                                              │
│  ◆ Choose your default coding tool                           │
│                                                              │
│  We detected these tools on your system:                     │
│                                                              │
│  ● Claude Code                                               │
│    Anthropic's agentic coding tool. Token-heavy on third-    │
│    party providers — expect higher costs.                    │
│  ○ OpenAI Codex                                              │
│    OpenAI's terminal coding agent. Runs one model through    │
│    the Responses API.                                        │
│  ○ OpenCode recommended                                      │
│    Open-source terminal coding agent. Efficient token usage, │
│    fast, and fully featured.                                 │
│  ○ Pi                                                        │
│    Minimal, customizable terminal coding agent. Runs one     │
│    active model — no tier routing.                           │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
  ↑↓ navigate  ·  enter select  ·  esc back

The last screen, after a key that works and a tool chosen. This one is from melious setup run again, where enter says finish setup; on a first run it says get started:

╭─── melious setup ────────────────────────────────────────────╮
│                                                              │
│  …                                                           │
│                                                              │
│  ✓ You're all set!                                           │
│                                                              │
│  ✓ Connected (54 models available)                           │
│  ✓ Default tool: claude-code                                 │
│                                                              │
│  Run melious launch to start your first session.             │
│                                                              │
╰──────────────────────────────────────────────────────────────╯
  enter finish setup  ·  esc back

Keys: ↑ ↓ to move, enter to select, ctrl+u to clear the key field, and q to quit from the welcome screen. esc goes back a step on every step, including the key check and the last screen; on the welcome screen, it quits.

With a key configured, bare melious opens the home menu. It has four items:

Item	What it's for	Command equivalent
1 Launch a coding tool	Start an agent	`melious launch`
2 Playground	Try any model on your own input	One command per model type — see Playground
3 Default models	Choose models for all tools or one tool	`melious tools model`
4 Settings	Account, defaults, trusted folders	`melious config`

The footer shows the installed version and whether an update is available; the overview shows the whole screen. Press 1 to 4 to open an item, or ↑ ↓ and enter. ? shows help. q, esc and ctrl+c quit from the home menu; on any other screen, esc goes back and ctrl+c quits. Where there's something to undo first, esc does that before it goes back: it closes a dialog or the help, clears a kept filter, leaves a text field, or stops a running request.

? lists the keys for the screen you're on, below the ones that work everywhere. On the Launch screen it looks like this:

  ❯ melious help
  ──────────────────────────────────────────────────

  Keyboard shortcuts

  EVERYWHERE
    esc          Back to the previous screen
    ?            Show this help
    ctrl+c       Quit at any time

  LAUNCH
    ↑↓/j/k       Move between tools
    enter        Launch the selected tool
    i            Install the selected tool
    m            Manage the selected tool

  Press any key to dismiss · screen: launch

When the list is taller than the terminal, as it is in the Playground at 32 rows, the heading stays put and the list scrolls under it. A line says how many more lines are above or below, ↑ ↓ scroll, and the legend says ↑↓ scroll · any other key dismisses.

The launcher doesn't take model flags, --trust-once, or passthrough arguments. Use melious launch when you need them.

Launch screen

Choose an agent from the list. The list shows each agent's install state, marks your default tool and our recommended one, and names the main model and preset a launch would use. At 80 columns, the descriptions are cut at the edge:

  Melious → Launch a coding tool
  ──────────────────────────────────────────────────

  model: glm-5.2  preset: balanced

→ ✓ Claude Code ● default
     Anthropic's agentic coding tool. Token-heavy on third-party providers — exp
  ✓ OpenAI Codex
     OpenAI's terminal coding agent. Runs one model through the Responses API.
  ✓ OpenCode recommended
     Open-source terminal coding agent. Efficient token usage, fast, and fully f
  ✓ Pi
     Minimal, customizable terminal coding agent. Runs one active model — no tie
  ✗ not installed Mistral Vibe
     Mistral's open-source terminal coding agent. Python-based, multi-provider s

  ↑↓ navigate  ·  enter launch  ·  i install  ·  m manage  ·  esc back

enter launches the selected agent in your current directory.
i installs it if it's missing.
m opens the manage dialog for an installed agent.

Launching from here follows the same steps as melious launch, including the trust prompt described below.

Playground

The Playground lets you try a chat, decision, transcription, rerank, embeddings, or image model on your own input, then shows the CLI command that does the same. It has its own page: Playground.

Default models

This screen sets the main, secondary and lightweight models. The layout has four parts:

Scope row: all tools, or one tool. ← and → switch between them. Setting a model for one tool overrides the all-tools value for that tool only.
Slot row: main, secondary or lightweight. tab moves to the next slot. For Claude Code the slots are named after its aliases: Opus, Sonnet and Haiku.
Current models: one line per slot with the model it uses now. On a tool's scope, global means the slot falls back to the all-tools model.
Model list: every chat model on your account, with the slot each one fills in brackets. ↑ ↓ to move.

To set a model, highlight it and press enter. It is saved to the slot and scope you chose.

The Claude Code scope, with nothing overridden yet and the list filtered to mini:

  Melious → Default models

  Scope  All tools  ‹ Claude Code ›  OpenAI Codex  OpenCode  Pi  Mistral Vibe
  Slot   ‹ Opus ›  Sonnet  Haiku
  Opus       glm-5.2                      global
  Sonnet     minimax-m3                   global
  Haiku      deepseek-v4-flash            global

  / mini

  › minimax-m2.5
    minimax-m3                       [Sonnet]


  enter set Opus  ·  ←→ scope  ·  tab tier  ·  / search  ·  x reset tool
  esc clear filter

At 80 columns the legend wraps onto a second line. It says esc clear filter while a filter is kept, as here, and esc back otherwise.

Other keys:

/ starts a search. Type to filter, enter keeps the filter, and esc clears it.
x clears the per-tool override for the selected tool, so it falls back to the all-tools models. On the all-tools scope it does nothing.
esc clears a kept filter first. With no filter, it goes back.

Settings

Settings lists eight rows. With the compiled defaults, it looks like this (the key mask is shortened):

  Melious → Settings

  › Account                 Signed in · sk-mel-****************
    Default tool            claude-code
    Preset                  balanced
    Default models          glm-5.2 · minimax-m3 · deepseek-v4-flash
    Default decision model  not set
    Auto-update             on
    Trusted folders         open to view
    Edit config file        ~/.melious/config.json

  ↑↓ move  ·  enter change  ·  ? help  ·  esc back

What each row is for:

Row	What it shows	Change it with
Account	Signed-in status, masked key	Sign out: `enter`, then `y` removes the saved key from this computer, `n` keeps it
Default tool	The agent `launch` starts with no argument	`enter`, then pick from the list
Preset	`balanced`, `speed`, `price` or `eco`	`enter`, then pick from the list
Default models	Summary of your model choices	Opens Default models
Default decision model	The model `melious decide` uses when you don't pass `--model`, or `not set`	`enter`, then pick from your decision models. `x` clears it, on the row or in the list.
Auto-update	Whether the update notice and background check run	`enter` to switch on or off
Trusted folders	The trusted-folders list	Opens the list
Edit config file	The path of `config.json`	`enter` opens it in your editor, like `melious config edit`

Keys: ↑ ↓ to move, enter to change or open a row, x to clear the default decision model, ? for help, esc to go back.

Changes are saved to your config right away. melious config show prints the same values. Default decision model is the models.decision key; see how model commands pick a model.

Trusted folders

The trusted-folders list shows each trusted folder. Two keys manage it:

a adds a folder.
x removes the selected one.

An entry that can't be read is marked as unreadable when you select it. Run melious trust prune to remove damaged records.

Trust prompts

The first time you launch an agent in a folder, Melious asks whether to trust it. The answer defaults to No. The prompt explains what trust allows: the agent runs as you, with your permissions, and can read and change files under the folder.

From the Launch screen, the question looks like this, with Cancel selected:

  ❯ melious launch

  ──────────────────────────────────────────────────
  TRUST

  ◆ Trust this workspace?

    ~/code/shop

    The agent runs as you, with your permissions —
    this is authorization, not a sandbox. Trust
    follows the location, not the contents: pulls,
    branch switches and a replacement checkout at
    this path stay trusted until you revoke it
    with melious trust remove <path>.

    ○ Trust this workspace
    ● Cancel

  ──────────────────────────────────────────────────

  → select  ·  enter confirm  ·  esc cancel

Some folders are too broad to trust safely. For these, Melious asks you to confirm twice: first a normal yes or no, then you type the phrase accept the risk. Nothing is trusted until both steps are done.

The same confirmation appears when you add a broad folder under Trusted folders. The first step there:

  Melious → Settings → Trusted folders

  ◆ This folder is too broad to trust by default.

    /home/example

  An agent there can read and change any file under it,
  and run commands as you. A home folder or a filesystem root
  holds keys, credentials and other projects.

  y continue  ·  n cancel

Press y, and the second step asks for the phrase:

  Melious → Settings → Trusted folders

  ◆ Type the phrase to confirm trust of /home/example

  ❯ accept the risk

  enter confirm  ·  esc cancel

For what a trust record stores and how to revoke it, see workspace trust.

Sign-out and removal

Signing out from Settings asks for confirmation before removing the saved key from this computer. melious auth logout does the same from the command line; see configuration.

Language and colour

The interface text is English only. Set NO_COLOR to turn off colour, or use --no-color with a command. See configuration for the other display options.