Global flags

--help

Every command explains itself:

ecko --help           # the command list
ecko pack --help      # what pack does, and its options
ecko test -h          # -h works too

Help prints to stdout and does nothing else, so it is safe to ask about a command before you are ready to run one.

AI flags

These apply to any command that can make an ai call - run, repl, test, explain, fix.

Each maps onto the matching environment variable, so a flag is a one-run override of your configuration. They go before the file: everything after the file belongs to your program, untouched, the way python and node work.

ecko --provider openrouter --model anthropic/claude-sonnet-4.5 report.ecko
ecko app.ecko --model small --port 8080    # all four words reach app.ecko

So a program of your own can have a --model or a --trace flag. A command that runs no program - ecko repl --provider ollama, ecko test --trace - takes the flags wherever they appear.

The API key has no flag. A key on the command line lands in your shell history and in the process list, where anyone on the machine can read it, so set ECKO_AI_API_KEY in the environment; --key is refused with an error saying so.

The full set of settings is environment variables only - see Environment variables. Configuration never lives in code.

--trace

Prints provider, model, token counts, latency and retries for each call. For a durable record set ECKO_AI_TRACE to a path and get JSONL instead - see Tracing.

--cache

Content-addressed: identical prompt, model and parameters return the stored response without a call, and without counting against a budget. Useful when iterating on the code around a prompt rather than the prompt itself. See Caching.

The API key

ECKO_AI_API_KEY in the environment, never on the command line. For a non-secret setting like the model, an environment block in ecko.json works too.