One-shot prompts

melious run sends one request to a Melious model and prints the response: a prompt from your arguments, your pipe, or your files, and an answer on stdout.

It's built for shell work: pipelines, scripts, and questions you'd otherwise open a chat tab for. There's no conversation or REPL. Every invocation is one request, and nothing is remembered between them. When you want an agent that works in your project, use melious launch instead.

Send a prompt

A prompt as an argument:

melious run "Name three Hanseatic cities and the river each one sits on"

A prompt from stdin, with no argument:

melious run < question.txt

Piped input plus instructions for what to do with it:

git diff | melious run "Summarize these changes for a reviewer"

A file as context, plus a prompt:

melious run -f src/main.go "Explain what this code does"

A file as the whole prompt:

melious run -f prompt.md

run needs a key (see configuration). Without one it fails before it reads any input.

How the input is put together

Melious builds one user message from up to three sources, in this order, separated by blank lines:

1. the files from --file
2. stdin
3. the prompt arguments, joined with spaces

If the result is empty or only whitespace, the run fails with no prompt provided; pass a prompt, pipe input, or use --file before any request is sent.

Melious reads stdin whenever it isn't a terminal, even when you also pass a prompt argument. That's what makes git diff | melious run "…" work, and it also means a pipe that never closes keeps run waiting. In a script or CI job with nothing to pipe, redirect stdin from /dev/null. A single stdin line longer than 1 MiB fails the run.

Set a system prompt

Inline:

melious run --system "You are a senior Go reviewer. Be brief." -f src/auth.go "Review this"

From a file, when it's long or you want it under version control:

melious run --system-file review-rules.md -f src/auth.go "Review this"

A nonempty --system wins over --system-file, which wins over run.system_prompt in your config. If you pass both flags, Melious warns on stderr that --system-file was ignored. A system file with no contents means no system prompt for that run, even if one is configured.

A system prompt on its own isn't input: melious run --system "…" with nothing else still fails with no prompt provided. An unreadable --system-file fails the run before Melious reads stdin or any --file.

Choose the output

The response always goes to stdout. Decoration and diagnostics go to stderr: the model tag above the response, the Loaded <file> lines, warnings, and errors. --quiet drops the Loaded lines.

Streaming follows run.stream in your config, which defaults to on. --no-stream waits for the whole response; --no-stream=false streams even when your config turns streaming off. A streamed request gives up after 5 minutes and a non-streamed one after 30 seconds.

Plain text for files and pipes

--raw prints the response and nothing else: no model tag, no footer, and no newline added by Melious. Newlines the model writes are left alone.

git diff --staged | melious run --raw "Write a one-line commit message for this diff" > msg.txt

JSON

--json waits for the full response and prints it as the API returned it, which is the form to parse in scripts:

melious run --json "Name three Hanseatic cities" > response.json

The shape, trimmed:

{
  "id": "<RESPONSE_ID>",
  "object": "chat.completion",
  "created": 1758700000,
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hamburg on the Elbe, …" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 16, "completion_tokens": 42, "total_tokens": 58 },
  "billing_cost": { "energy": "…", "credits": "…", "paid_with": "…" },
  "environment_impact": { "carbon_g_co2": 0.12, "renewable_percent": 85, "…": "…" }
}

usage, billing_cost, and environment_impact appear only when the API returns them, so check for them before you read them. --json ignores --raw and --show-env. Scripting covers exit statuses and the other commands' JSON.

Environmental impact

melious run --show-env "Name three Hanseatic cities"

--show-env turns streaming off and, after the response, prints a footer to stdout with the request's estimated CO₂, renewable share, provider and location, token count, and energy cost. We turn streaming off because the API only returns these figures on a complete response. The footer is per request, and it only appears when the API returns environmental data. Environmental impact explains the numbers.

Pick a model and preset

Without flags, run uses your configured main model and default preset. For one run:

melious run --model <MODEL_ID> --preset eco "Name three Hanseatic cities"

--preset is one of balanced, speed, price, or eco — see routing for what each one trades. balanced sends the model ID unchanged, and the other three add a :<preset> suffix to it, replacing any suffix already there. Any other preset fails before the request.

The other parameters:

• --temperature takes a value from 0 to 2. Anything outside that range fails before the request.
• --max-tokens caps the length of the response.
• --top-p sets nucleus sampling.

Include files

Pass -f (or --file) once per file or pattern:

melious run -f src/main.go -f src/handler.go "How do these files interact?"

Quote wildcards so your shell passes them to Melious unexpanded. ** matches any number of directories:

melious run -f "src/**/*.ts" "Find likely bugs in this code"

Each file is sent as a ### File: <path> heading followed by its contents in a code block, so the model sees which file is which. A file named twice, for example once by path and once by a wildcard, is sent once.

What wildcards skip, unless the pattern names them:

• hidden files and directories (on Windows, those with the hidden attribute)
• node_modules and vendor directories

So "src/**/*.ts" passes over src/node_modules, while "src/node_modules/**/*.ts" and "src/.config/*.ts" include what they name. Wildcards don't descend into symlinked directories, but a symlinked file is followed.

A path that exists exactly as written is read as that file, even if its name contains *, ?, [, or {. Inside a pattern, escape those characters with a backslash to match them literally.

Limits

File context is capped at 256 files, 1 MiB per file, and 8 MiB in total. Going over any limit fails the whole run, even when a wildcard swept up the file. We'd rather stop than answer from a context you think is complete and isn't.

Melious doesn't detect binary files. A wildcard that catches an image sends it as text and counts it against the limits, so keep patterns specific.

Wildcards and explicit paths

A wildcard is forgiving about what it finds, and a path you type out is not:

A wildcard that matches nothing leaves the run with whatever other input you gave it. If that's nothing, the run fails with no prompt provided.