CLI
Lunos CLI options and commands.
The Lunos CLI by default starts the TUI when run without any arguments.
lunosBut it also accepts commands as documented on this page. This allows you to interact with Lunos programmatically.
lunos run "Explain how closures work in JavaScript"tui
Start the Lunos terminal user interface.
lunos [project]Flags
| Flag | Short | Description |
|---|---|---|
--continue | -c | Continue the last session |
--session | -s | Session ID to continue |
--fork | Fork the session when continuing (use with --continue or --session) | |
--prompt | Prompt to use | |
--model | -m | Model to use in the form of provider/model |
--agent | Agent to use | |
--auto | Auto-approve permissions that are not explicitly denied | |
--port | Port to listen on | |
--hostname | Hostname to listen on | |
--mdns | Enable mDNS discovery | |
--mdns-domain | Custom mDNS domain name | |
--cors | Additional browser origin(s) to allow CORS |
Commands
The Lunos CLI also has the following commands.
agent
Manage agents for Lunos.
lunos agent [command]create
Create a new agent with custom configuration.
lunos agent createThis command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.
Flags
| Flag | Short | Description |
|---|---|---|
--path | Directory to write the agent file to (defaults to global or .opencode/agent based on the prompt) | |
--description | What the agent should do | |
--mode | Agent mode: all, primary, or subagent | |
--permissions | Comma-separated list of permissions to allow (default: all). Available: bash, read, edit, glob, grep, webfetch, task, todowrite, websearch, lsp, skill. Anything omitted is denied. Alias: --tools | |
--model | -m | Model to use, in provider/model format |
Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.
list
List all available agents.
lunos agent listattach
Attach a terminal to an already running Lunos backend server started via serve or web commands.
lunos attach [url]This allows using the TUI with a remote Lunos backend. For example:
# Start the backend server for web/mobile accesslunos web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backendlunos attach http://10.20.30.40:4096Flags
| Flag | Short | Description |
|---|---|---|
--dir | Working directory to start TUI in | |
--continue | -c | Continue the last session |
--session | -s | Session ID to continue |
--fork | Fork the session when continuing (use with --continue or --session) | |
--password | -p | Basic auth password (defaults to OPENCODE_SERVER_PASSWORD) |
--username | -u | Basic auth username (defaults to OPENCODE_SERVER_USERNAME or lunos) |
auth
Command to manage credentials and login for providers.
lunos auth [command]login
Lunos is powered by the provider list at Models.dev, so you can use lunos auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/opencode/auth.json.
lunos auth loginWhen Lunos starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.
Flags
| Flag | Short | Description |
|---|---|---|
--provider | -p | Provider ID or name to log in to |
--method | -m | Login method label to use, skipping method selection |
list
Lists all the authenticated providers as stored in the credentials file.
lunos auth listOr the short version.
lunos auth lslogout
Logs you out of a provider by clearing it from the credentials file.
lunos auth logoutgithub
Manage the GitHub agent for repository automation.
lunos github [command]run
Run the GitHub agent. This is typically used in GitHub Actions.
lunos github runFlags
| Flag | Description |
|---|---|
--event | GitHub mock event to run the agent for |
--token | GitHub personal access token |
mcp
Manage Model Context Protocol servers.
lunos mcp [command]add
Add an MCP server to your configuration.
lunos mcp addThis command will guide you through adding either a local or remote MCP server.
list
List all configured MCP servers and their connection status.
lunos mcp listOr use the short version.
lunos mcp lsauth
Authenticate with an OAuth-enabled MCP server.
lunos mcp auth [name]If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.
You can also list OAuth-capable servers and their authentication status.
lunos mcp auth listOr use the short version.
lunos mcp auth lslogout
Remove OAuth credentials for an MCP server.
lunos mcp logout [name]debug
Debug OAuth connection issues for an MCP server.
lunos mcp debug <name>models
List all available models from configured providers.
lunos models [provider]This command displays all models available across your configured providers in the format provider/model.
This is useful for figuring out the exact model name to use in your config.
You can optionally pass a provider ID to filter models by that provider.
lunos models anthropicFlags
| Flag | Description |
|---|---|
--refresh | Refresh the models cache from models.dev |
--verbose | Use more verbose model output (includes metadata like costs) |
Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in Lunos.
lunos models --refreshrun
Run Lunos in non-interactive mode by passing a prompt directly.
lunos run [message..]This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.
lunos run Explain the use of context in GoYou can also attach to a running lunos serve instance to avoid MCP server cold boot times on every run:
# Start a headless server in one terminallunos serve
# In another terminal, run commands that attach to itlunos run --attach http://localhost:4096 "Explain async/await in JavaScript"Flags
| Flag | Short | Description |
|---|---|---|
--command | The command to run, use message for args | |
--continue | -c | Continue the last session |
--session | -s | Session ID to continue |
--fork | Fork the session when continuing (use with --continue or --session) | |
--share | Share the session | |
--model | -m | Model to use in the form of provider/model |
--agent | Agent to use | |
--file | -f | File(s) to attach to message |
--format | Format: default (formatted) or json (raw JSON events) | |
--title | Title for the session (uses truncated prompt if no value provided) | |
--attach | Attach to a running Lunos server (e.g., http://localhost:4096) | |
--password | -p | Basic auth password (defaults to OPENCODE_SERVER_PASSWORD) |
--username | -u | Basic auth username (defaults to OPENCODE_SERVER_USERNAME or lunos) |
--dir | Directory to run in, or path on the remote server when attaching | |
--port | Port for the local server (defaults to random port) | |
--variant | Model variant (provider-specific reasoning effort) | |
--thinking | Show thinking blocks | |
--auto | Auto-approve permissions that are not explicitly denied |
serve
Start a headless Lunos server for API access. Check out the server docs for the full HTTP interface.
lunos serveThis starts an HTTP server that provides API access to Lunos functionality without the TUI interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to lunos).
Flags
| Flag | Description |
|---|---|
--port | Port to listen on |
--hostname | Hostname to listen on |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
project
Named projects: several repositories or directories counted as one, for example “Axsion web” for
axsion-web, axsion-api and infra. A repository is a project of its own without any of this.
Named projects are kept on this computer only. A session counts in the project of its working
directory (the deepest folder wins), a subagent’s in its parent’s; /sessions can move one.
lunos project create "Axsion web" ../axsion-web ../axsion-apilunos project listlunos project add "Axsion web" ../infralunos project remove "Axsion web" ../axsion-apilunos project rename "Axsion web" "Axsion"lunos project archive "Axsion"A project is named by its name or its id (pgrp_…). Folders are paths, relative to where you run
the command; leaving them out means the current folder. A folder can be in one live project at a
time. Archiving keeps the project and its history, but its folders count in their repositories’
projects again; lunos project archive <project> --undo brings it back.
Flags
| Flag | Description |
|---|---|
--json | Print the project (or the list) as JSON; a refusal as error |
--archived | With list: include archived projects |
--empty | With create: create it without any folder |
budget
Project budgets. A project’s budget is kept on this computer with the project, never in a config
file a repository could change. Every model step in the project counts against it, subagents’,
lunos run’s and scheduled agents’ included, and Claude Code turns at the cost Claude Code reports.
Prices come from the model catalogue, in USD, converted at budget.usd_rate (a fixed rate you set;
default 0.9). A model without a price counts as “unknown cost”, never as 0: set one with
provider.<id>.models.<id>.cost.
lunos budget set "Axsion web" 50 # €50 a month, from the 1stlunos budget set . 200 --period total --per-day 20 # this folder's projectlunos budget status --jsonlunos budget export --period 2026-10 -o october.csvlunos budget set "Axsion web" --clearBefore every step, Lunos checks what’s left. At the start of a turn it also checks the turn’s
estimate (from the context size, the model’s price and the session’s recent turns). What happens at
the limit is budget.on_limit, or --on-limit for one project:
warn: a warning, and the turn runs.ask(the default): you choose Run anyway, Use a cheaper model… or Stop.stop: no new turn or step starts until the period resets or the budget is raised. A step already running always finishes.
In lunos run, CI and unattended agents nobody can answer, so ask stops, and the run exits with
code 3 and “budget exceeded”. Each of budget.thresholds (default 50, 80 and 100%) alerts once per
period. An organisation’s budget comes from managed config, budget.organisation locked with
"$locked": ["budget.organisation"]; members see it and can’t raise it.
Flags
| Flag | Description |
|---|---|
--project | With status and export: a named project; default: this folder’s |
--json | With status and set: print JSON |
--period | With set: monthly, weekly or total; with export: 2026-10 |
--reset-day | With set --period monthly: the day it resets on, 1 to 28 |
--per-session | With set: the most one session may spend, subagents included |
--per-day | With set: the most the project may spend in a day |
--on-limit | With set: warn, ask or stop for this project |
--output | With export: write the CSV to this file |
session
Manage Lunos sessions.
lunos session [command]list
List all Lunos sessions.
lunos session listFlags
| Flag | Short | Description |
|---|---|---|
--max-count | -n | Limit to N most recent sessions |
--format | Output format: table or json (table) |
delete
Delete sessions for good: their history, subagent sessions and queued prompts. Files in your
projects are never touched, and a Claude Code or Codex session keeps that tool’s own history. A
shared session’s link is removed first, and with session sync on, the synced copy is deleted too.
Console shares made from a session or its subagents with lunos share (or /share to your
organisation’s console) are revoked first; if one can’t be, the session is kept and the reason is
printed. Console shares made before Lunos recorded which session they came from aren’t linked to it
and stay live: find them with lunos share list and revoke them with lunos share revoke <id>.
lunos session delete <sessionID...>lunos session delete --archived --older-than 30d --yesIt prints what it deleted and what it skipped, and why.
Flags
| Flag | Short | Description |
|---|---|---|
--archived | Delete every archived session instead of the ids given | |
--older-than | With --archived: only those last active before this, e.g. 30d | |
--project | With --archived: only sessions of the project at this path | |
--stop | Stop running or waiting sessions first (otherwise they are skipped) | |
--keep-cloud | Keep the synced copies on Lunos Cloud | |
--keep-shares | Leave the console shares made from them live instead of revoking them | |
--yes | -y | Don’t ask for confirmation (needed with --archived in a script) |
stats
Show token usage and cost statistics for your Lunos sessions.
lunos statsFlags
| Flag | Description |
|---|---|
--days | Show stats for the last N days (all time) |
--tools | Number of tools to show (all) |
--models | Show model usage breakdown (hidden by default). Pass a number to show top N |
--project | Filter by project: a named project’s name or id, or a repository project’s id (all projects, empty string: current project) |
--json | Print the statistics as JSON |
memory
Review long-term memory (see Rules: long-term memory). list, show and export --format markdown read what is stored without starting memory. A bundle export starts memory to read the graph, unless you pass --no-graph.
lunos memory list [--scope project|user]lunos memory show <id>lunos memory search <query>lunos memory forget <id>lunos memory purge --scope project|user --yeslunos memory export [--format bundle|markdown] [--scope project|user|both] [--since <date>] [--out <path>] [--zip] [--encrypt] [--no-graph] [--include-index] [--dir <path>]lunos memory import <path> [--scope project|user] [--yes] [--dry-run] [--as-facts] [--include-conflicts]lunos memory migrate --to neo4j [--scope project|user] [--yes] [--include-conflicts]lunos memory statuslunos memory stats [--scope project|user] [--days N] [--json]lunos memory setup [--yes] [--project] [--no-check]lunos memory check [--json]-
exportwrites all of memory as a versioned bundle (facts, graph, notes and provenance) to./lunos-memory-<time>/, or a.zipwith--zip, or an encrypted.zip.encwith--encrypt. See Rules: exporting memory. -
export --format markdownwrites one Markdown file per fact, with its provenance, to.opencode/memory/export/(or--dir) so you can review memory in git. -
forgetremoves the fact from memory and from that Markdown export folder. Bundles already written are snapshots and keep it. -
importreads a bundle, Markdown, orAGENTS.md/CLAUDE.md/ Claude Code memory, verifies and screens every fact, and shows a preview of new, duplicate, conflict and rejected rows. It writes only with--yes. See Rules: importing memory. -
purgedeletes a memory’s stored facts and graph. Your notes in.opencode/memory/*.mdare kept. -
migrate --to neo4jmoves this machine’s embedded memory into the external database set inmemory.backend: it exports a bundle and imports it with the same preview, keeping each fact’s id and provenance. It writes only with--yes. See Rules: an external memory database. -
statusshows whether memory is on, the backend and whether it can be reached, and each scope’s fact count and last write. -
statsprints what/memory’s Overview and Activity show (see Rules: memory analytics).--dayslimits growth and recall to the last N days.--jsonprints one object,version: 1, with these fields:status:on,reason,backend,encryption, retention, and ledgerhealth.scopes[]:counts(active,outdated,expiring,expired,quarantined),lastWrite,error,charsandtokens.sources: counts bysource,agent,kind,nativeandimported.growth[]: perweekandscope, the factsadded,outdated,forgottenandexpired.recall:audit,dataSince,total,perDay[],origin,hitRate,avgFactsandtruncatedRate.top[](id,count,last) andsupersession(count,chains).facts: each recalled fact’srecallsandlast.groups: the fact ids behind each count, e.g.never,state:project:outdated,source:file.
-
setupasks the setup wizard’s questions: on or off, where memory is kept, the model, the first-start download, retention and encryption. It then checks memory works and saves to your user config (--projectfor this project).--yesaccepts every recommended answer. Without a terminal it needs--yes. A failed check still saves, but exits with 1. -
checkremembers a test fact, recalls it and removes it, then says ✓ or the error and how to fix it (--jsonfor scripts). The first run downloads the engine and the embedding model.
settings
View and change settings. With no subcommand it opens the TUI on the settings screen.
lunos settingslunos settings list [--json]lunos settings get <key>lunos settings set <key> <value> [--project]setwrites your user config, or.opencode/opencode.jsonwith--project, keeping comments. It validates the value against the config schema and refuses keys locked by your organisation, exiting non-zero with the reason. Lists take comma-separated values or JSON; structured settings take JSON.- See Config: Settings.
export
Export session data as JSON.
lunos export [sessionID]If you don’t provide a session ID, you’ll be prompted to select from available sessions.
Flags
| Flag | Description |
|---|---|
--sanitize | Redact sensitive transcript/file data |
import
Import session data from a JSON file or Lunos share URL.
lunos import <file>You can import from a local file or an Lunos share URL.
lunos import session.jsonlunos import https://share.example.com/share/abc123web
Start a headless Lunos server with a web interface.
lunos webThis starts an HTTP server and opens a web browser to access Lunos through a web interface. Set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to lunos).
Flags
| Flag | Description |
|---|---|
--port | Port to listen on |
--hostname | Hostname to listen on |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
acp
Start an ACP (Agent Client Protocol) server.
lunos acpThis command starts an ACP server that communicates via stdin/stdout using nd-JSON.
Flags
| Flag | Description |
|---|---|
--cwd | Working directory |
--port | Port to listen on |
--hostname | Hostname to listen on |
--mdns | Enable mDNS discovery |
--mdns-domain | Custom mDNS domain name |
--cors | Additional browser origin(s) to allow CORS |
plugin
Install a plugin and update your config.
lunos plugin <module>Or use the alias.
lunos plug <module>Flags
| Flag | Short | Description |
|---|---|---|
--global | -g | Install in global config |
--force | -f | Replace existing plugin version |
pr
Fetch and checkout a GitHub PR branch, then run Lunos.
lunos pr <number>db
Database tools.
lunos db [query]Flags
| Flag | Description |
|---|---|
--format | Output format: json or tsv |
path
Print the database path.
lunos db pathdebug
Debugging and troubleshooting tools.
lunos debug [command]uninstall
Uninstall Lunos and remove all related files.
lunos uninstallFlags
| Flag | Short | Description |
|---|---|---|
--keep-config | -c | Keep configuration files |
--keep-data | -d | Keep session data and snapshots |
--dry-run | Show what would be removed without removing | |
--force | -f | Skip confirmation prompts |
changelog
Shows what changed in Lunos, from the release notes built into this version, so it works offline.
lunos changelog [--since <version>] [--full] [--json]Without options it summarizes the version you have. --since 1.18.43 covers every version after
1.18.43, skipped ones included. The summary lists behaviour changes and security entries first, then
what’s new and a count of fixes, one line each with its ticket. --full prints the notes as written,
and --json prints the entries as { version, section, text, tickets } for scripts. A version with
no notes says No notes for X.Y.Z.
update
Updates Lunos to the latest version or a specific version. lunos upgrade is an alias and still works.
lunos update [target]To update to the latest version.
lunos updateWhen you’re already on the latest version, this prints Lunos is up to date (X.Y.Z). and exits 0.
To update to a specific version.
lunos update v0.1.48While it runs, a spinner shows the step and the elapsed time: checking for the latest version,
downloading and installing lunos-ai, then verifying the installed version. If a step takes longer
than a minute, the line adds that the package manager is still working; there’s no timeout. With
NO_COLOR or TERM=dumb you get one Updating… (step) line per step instead of the spinner, and
when the output isn’t a terminal (a pipe, CI) one plain line per step with no escape codes.
Ctrl+C cancels while Lunos is still checking for the version. Once the package manager is installing
it runs to the end, even if you press Ctrl+C or close the TUI, because stopping it halfway could leave
no working lunos.
After a successful update, Lunos prints what changed since the version you had (the same summary
as lunos changelog --since <your version>) before the restart hint.
If the update fails, Lunos prints the command to run by hand and exits with code 1. For npm installs
that’s npm i -g lunos-ai@<version> --allow-scripts=lunos-ai.
A running TUI keeps using the old version until it restarts. After /update in the TUI, run
/restart: it starts the newly installed version back in the same session. See
/restart.
New version notice
Every time Lunos starts it asks the npm registry (lunos-ai, or the registry in your .npmrc) for
the latest version. The check runs in the background, never delays startup, and gives up after 3
seconds; if it fails, the last known result is used.
- In the TUI, the bottom-right corner shows
There is a new version: X.Y.Z — please run lunos updateon every screen until you update (New version: X.Y.Z · lunos updatebelow 100 columns). - Plain commands such as
lunos modelsprintThere is a new version: X.Y.Z — please run "lunos update"to stderr, at most once a day. It never goes to stdout, so piped output stays clean.
No check is made, and no notice shown, with "autoupdate": false, LUNOS_DISABLE_AUTOUPDATE=1,
LUNOS_OFFLINE=1, or when an organisation policy sets "autoupdate": false.
Flags
| Flag | Short | Description |
|---|---|---|
--method | -m | The installation method that was used; curl, npm, pnpm, bun, brew |
Global Flags
The Lunos CLI takes the following global flags.
| Flag | Short | Description |
|---|---|---|
--help | -h | Display help |
--version | -v | Print version number |
--print-logs | Print logs to stderr | |
--log-level | Log level (DEBUG, INFO, WARN, ERROR) | |
--pure | Run without external plugins |
Environment variables
Lunos can be configured using environment variables.
| Variable | Type | Description |
|---|---|---|
OPENCODE_AUTO_SHARE | boolean | Automatically share sessions |
OPENCODE_GIT_BASH_PATH | string | Path to Git Bash executable on Windows |
OPENCODE_CONFIG | string | Path to config file |
OPENCODE_TUI_CONFIG | string | Path to TUI config file |
OPENCODE_CONFIG_DIR | string | Path to config directory |
OPENCODE_CONFIG_CONTENT | string | Inline json config content |
OPENCODE_DISABLE_AUTOUPDATE | boolean | Disable automatic update checks |
OPENCODE_DISABLE_PRUNE | boolean | Disable pruning of old data |
OPENCODE_DISABLE_TERMINAL_TITLE | boolean | Disable automatic terminal title updates |
OPENCODE_PERMISSION | string | Inlined json permissions config |
OPENCODE_DISABLE_DEFAULT_PLUGINS | boolean | Disable default plugins |
OPENCODE_DISABLE_LSP_DOWNLOAD | boolean | Disable automatic LSP server downloads |
OPENCODE_ENABLE_EXPERIMENTAL_MODELS | boolean | Enable experimental models |
OPENCODE_DISABLE_AUTOCOMPACT | boolean | Disable automatic context compaction |
OPENCODE_DISABLE_CLAUDE_CODE | boolean | Disable reading from .claude (prompt + skills) |
OPENCODE_DISABLE_CLAUDE_CODE_PROMPT | boolean | Disable reading ~/.claude/CLAUDE.md |
OPENCODE_DISABLE_CLAUDE_CODE_SKILLS | boolean | Disable loading .claude/skills |
OPENCODE_DISABLE_MODELS_FETCH | boolean | Disable fetching models from remote sources |
OPENCODE_DISABLE_MOUSE | boolean | Disable mouse capture in the TUI |
OPENCODE_FAKE_VCS | string | Fake VCS provider for testing purposes |
OPENCODE_CLIENT | string | Client identifier (defaults to cli) |
OPENCODE_ENABLE_EXA | boolean | Enable Exa web search tools |
OPENCODE_ENABLE_PARALLEL | boolean | Enable Parallel web search tools |
OPENCODE_SERVER_PASSWORD | string | Enable basic auth for serve/web |
OPENCODE_SERVER_USERNAME | string | Override basic auth username (default lunos) |
OPENCODE_MODELS_URL | string | Custom URL for fetching models configuration |
Experimental
These environment variables enable experimental features that may change or be removed.
| Variable | Type | Description |
|---|---|---|
OPENCODE_EXPERIMENTAL | boolean | Enable the experimental umbrella flag |
OPENCODE_EXPERIMENTAL_ICON_DISCOVERY | boolean | Enable icon discovery |
OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT | boolean | Disable copy on select in TUI |
OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS | number | Default timeout for bash commands in ms |
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX | number | Max output tokens for LLM responses |
OPENCODE_EXPERIMENTAL_FILEWATCHER | boolean | Enable file watcher for entire dir |
OPENCODE_EXPERIMENTAL_OXFMT | boolean | Enable oxfmt formatter |
OPENCODE_EXPERIMENTAL_LSP_TOOL | boolean | Enable experimental LSP tool |
OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER | boolean | Disable file watcher |
OPENCODE_EXPERIMENTAL_EXA | boolean | Enable experimental Exa features |
OPENCODE_EXPERIMENTAL_LSP_TY | boolean | Enable TY LSP for python files |
OPENCODE_EXPERIMENTAL_PLAN_MODE | boolean | Enable plan mode |
OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS | boolean | Enable background subagent tasks |
OPENCODE_EXPERIMENTAL_EVENT_SYSTEM | boolean | Enable experimental event system |
OPENCODE_EXPERIMENTAL_NATIVE_LLM | boolean | Enable native LLM request path |
OPENCODE_EXPERIMENTAL_PARALLEL | boolean | Enable parallel web search execution |
OPENCODE_EXPERIMENTAL_SCOUT | boolean | Enable Scout subagent |
OPENCODE_EXPERIMENTAL_WORKSPACES | boolean | Enable workspace support |