Skip to content

CLI

Lunos CLI options and commands.

The Lunos CLI by default starts the TUI when run without any arguments.

Terminal window
lunos

But it also accepts commands as documented on this page. This allows you to interact with Lunos programmatically.

Terminal window
lunos run "Explain how closures work in JavaScript"

tui

Start the Lunos terminal user interface.

Terminal window
lunos [project]

Flags

FlagShortDescription
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--promptPrompt to use
--model-mModel to use in the form of provider/model
--agentAgent to use
--autoAuto-approve permissions that are not explicitly denied
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

Commands

The Lunos CLI also has the following commands.


agent

Manage agents for Lunos.

Terminal window
lunos agent [command]

create

Create a new agent with custom configuration.

Terminal window
lunos agent create

This 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

FlagShortDescription
--pathDirectory to write the agent file to (defaults to global or .opencode/agent based on the prompt)
--descriptionWhat the agent should do
--modeAgent mode: all, primary, or subagent
--permissionsComma-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-mModel to use, in provider/model format

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.


list

List all available agents.

Terminal window
lunos agent list

attach

Attach a terminal to an already running Lunos backend server started via serve or web commands.

Terminal window
lunos attach [url]

This allows using the TUI with a remote Lunos backend. For example:

Terminal window
# Start the backend server for web/mobile access
lunos web --port 4096 --hostname 0.0.0.0
# In another terminal, attach the TUI to the running backend
lunos attach http://10.20.30.40:4096

Flags

FlagShortDescription
--dirWorking directory to start TUI in
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--password-pBasic auth password (defaults to OPENCODE_SERVER_PASSWORD)
--username-uBasic auth username (defaults to OPENCODE_SERVER_USERNAME or lunos)

auth

Command to manage credentials and login for providers.

Terminal window
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.

Terminal window
lunos auth login

When 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
FlagShortDescription
--provider-pProvider ID or name to log in to
--method-mLogin method label to use, skipping method selection

list

Lists all the authenticated providers as stored in the credentials file.

Terminal window
lunos auth list

Or the short version.

Terminal window
lunos auth ls

logout

Logs you out of a provider by clearing it from the credentials file.

Terminal window
lunos auth logout

github

Manage the GitHub agent for repository automation.

Terminal window
lunos github [command]

run

Run the GitHub agent. This is typically used in GitHub Actions.

Terminal window
lunos github run
Flags
FlagDescription
--eventGitHub mock event to run the agent for
--tokenGitHub personal access token

mcp

Manage Model Context Protocol servers.

Terminal window
lunos mcp [command]

add

Add an MCP server to your configuration.

Terminal window
lunos mcp add

This command will guide you through adding either a local or remote MCP server.


list

List all configured MCP servers and their connection status.

Terminal window
lunos mcp list

Or use the short version.

Terminal window
lunos mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

Terminal window
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.

Terminal window
lunos mcp auth list

Or use the short version.

Terminal window
lunos mcp auth ls

logout

Remove OAuth credentials for an MCP server.

Terminal window
lunos mcp logout [name]

debug

Debug OAuth connection issues for an MCP server.

Terminal window
lunos mcp debug <name>

models

List all available models from configured providers.

Terminal window
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.

Terminal window
lunos models anthropic

Flags

FlagDescription
--refreshRefresh the models cache from models.dev
--verboseUse 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.

Terminal window
lunos models --refresh

run

Run Lunos in non-interactive mode by passing a prompt directly.

Terminal window
lunos run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

Terminal window
lunos run Explain the use of context in Go

You can also attach to a running lunos serve instance to avoid MCP server cold boot times on every run:

Terminal window
# Start a headless server in one terminal
lunos serve
# In another terminal, run commands that attach to it
lunos run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

FlagShortDescription
--commandThe command to run, use message for args
--continue-cContinue the last session
--session-sSession ID to continue
--forkFork the session when continuing (use with --continue or --session)
--shareShare the session
--model-mModel to use in the form of provider/model
--agentAgent to use
--file-fFile(s) to attach to message
--formatFormat: default (formatted) or json (raw JSON events)
--titleTitle for the session (uses truncated prompt if no value provided)
--attachAttach to a running Lunos server (e.g., http://localhost:4096)
--password-pBasic auth password (defaults to OPENCODE_SERVER_PASSWORD)
--username-uBasic auth username (defaults to OPENCODE_SERVER_USERNAME or lunos)
--dirDirectory to run in, or path on the remote server when attaching
--portPort for the local server (defaults to random port)
--variantModel variant (provider-specific reasoning effort)
--thinkingShow thinking blocks
--autoAuto-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.

Terminal window
lunos serve

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional 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.

Terminal window
lunos project create "Axsion web" ../axsion-web ../axsion-api
lunos project list
lunos project add "Axsion web" ../infra
lunos project remove "Axsion web" ../axsion-api
lunos 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

FlagDescription
--jsonPrint the project (or the list) as JSON; a refusal as error
--archivedWith list: include archived projects
--emptyWith 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.

Terminal window
lunos budget set "Axsion web" 50 # €50 a month, from the 1st
lunos budget set . 200 --period total --per-day 20 # this folder's project
lunos budget status --json
lunos budget export --period 2026-10 -o october.csv
lunos budget set "Axsion web" --clear

Before 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

FlagDescription
--projectWith status and export: a named project; default: this folder’s
--jsonWith status and set: print JSON
--periodWith set: monthly, weekly or total; with export: 2026-10
--reset-dayWith set --period monthly: the day it resets on, 1 to 28
--per-sessionWith set: the most one session may spend, subagents included
--per-dayWith set: the most the project may spend in a day
--on-limitWith set: warn, ask or stop for this project
--outputWith export: write the CSV to this file

session

Manage Lunos sessions.

Terminal window
lunos session [command]

list

List all Lunos sessions.

Terminal window
lunos session list
Flags
FlagShortDescription
--max-count-nLimit to N most recent sessions
--formatOutput 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>.

Terminal window
lunos session delete <sessionID...>
lunos session delete --archived --older-than 30d --yes

It prints what it deleted and what it skipped, and why.

Flags
FlagShortDescription
--archivedDelete every archived session instead of the ids given
--older-thanWith --archived: only those last active before this, e.g. 30d
--projectWith --archived: only sessions of the project at this path
--stopStop running or waiting sessions first (otherwise they are skipped)
--keep-cloudKeep the synced copies on Lunos Cloud
--keep-sharesLeave the console shares made from them live instead of revoking them
--yes-yDon’t ask for confirmation (needed with --archived in a script)

stats

Show token usage and cost statistics for your Lunos sessions.

Terminal window
lunos stats

Flags

FlagDescription
--daysShow stats for the last N days (all time)
--toolsNumber of tools to show (all)
--modelsShow model usage breakdown (hidden by default). Pass a number to show top N
--projectFilter by project: a named project’s name or id, or a repository project’s id (all projects, empty string: current project)
--jsonPrint 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.

Terminal window
lunos memory list [--scope project|user]
lunos memory show <id>
lunos memory search <query>
lunos memory forget <id>
lunos memory purge --scope project|user --yes
lunos 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 status
lunos memory stats [--scope project|user] [--days N] [--json]
lunos memory setup [--yes] [--project] [--no-check]
lunos memory check [--json]
  • export writes all of memory as a versioned bundle (facts, graph, notes and provenance) to ./lunos-memory-<time>/, or a .zip with --zip, or an encrypted .zip.enc with --encrypt. See Rules: exporting memory.

  • export --format markdown writes one Markdown file per fact, with its provenance, to .opencode/memory/export/ (or --dir) so you can review memory in git.

  • forget removes the fact from memory and from that Markdown export folder. Bundles already written are snapshots and keep it.

  • import reads a bundle, Markdown, or AGENTS.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.

  • purge deletes a memory’s stored facts and graph. Your notes in .opencode/memory/*.md are kept.

  • migrate --to neo4j moves this machine’s embedded memory into the external database set in memory.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.

  • status shows whether memory is on, the backend and whether it can be reached, and each scope’s fact count and last write.

  • stats prints what /memory’s Overview and Activity show (see Rules: memory analytics). --days limits growth and recall to the last N days.

    --json prints one object, version: 1, with these fields:

    • status: on, reason, backend, encryption, retention, and ledger health.
    • scopes[]: counts (active, outdated, expiring, expired, quarantined), lastWrite, error, chars and tokens.
    • sources: counts by source, agent, kind, native and imported.
    • growth[]: per week and scope, the facts added, outdated, forgotten and expired.
    • recall: audit, dataSince, total, perDay[], origin, hitRate, avgFacts and truncatedRate.
    • top[] (id, count, last) and supersession (count, chains).
    • facts: each recalled fact’s recalls and last.
    • groups: the fact ids behind each count, e.g. never, state:project:outdated, source:file.
  • setup asks 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 (--project for this project). --yes accepts every recommended answer. Without a terminal it needs --yes. A failed check still saves, but exits with 1.

  • check remembers a test fact, recalls it and removes it, then says ✓ or the error and how to fix it (--json for 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.

Terminal window
lunos settings
lunos settings list [--json]
lunos settings get <key>
lunos settings set <key> <value> [--project]
  • set writes your user config, or .opencode/opencode.json with --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.

Terminal window
lunos export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

Flags

FlagDescription
--sanitizeRedact sensitive transcript/file data

import

Import session data from a JSON file or Lunos share URL.

Terminal window
lunos import <file>

You can import from a local file or an Lunos share URL.

Terminal window
lunos import session.json
lunos import https://share.example.com/share/abc123

web

Start a headless Lunos server with a web interface.

Terminal window
lunos web

This 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

FlagDescription
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

Terminal window
lunos acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

FlagDescription
--cwdWorking directory
--portPort to listen on
--hostnameHostname to listen on
--mdnsEnable mDNS discovery
--mdns-domainCustom mDNS domain name
--corsAdditional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

Terminal window
lunos plugin <module>

Or use the alias.

Terminal window
lunos plug <module>

Flags

FlagShortDescription
--global-gInstall in global config
--force-fReplace existing plugin version

pr

Fetch and checkout a GitHub PR branch, then run Lunos.

Terminal window
lunos pr <number>

db

Database tools.

Terminal window
lunos db [query]

Flags

FlagDescription
--formatOutput format: json or tsv

path

Print the database path.

Terminal window
lunos db path

debug

Debugging and troubleshooting tools.

Terminal window
lunos debug [command]

uninstall

Uninstall Lunos and remove all related files.

Terminal window
lunos uninstall

Flags

FlagShortDescription
--keep-config-cKeep configuration files
--keep-data-dKeep session data and snapshots
--dry-runShow what would be removed without removing
--force-fSkip confirmation prompts

changelog

Shows what changed in Lunos, from the release notes built into this version, so it works offline.

Terminal window
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.

Terminal window
lunos update [target]

To update to the latest version.

Terminal window
lunos update

When 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.

Terminal window
lunos update v0.1.48

While 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 update on every screen until you update (New version: X.Y.Z · lunos update below 100 columns).
  • Plain commands such as lunos models print There 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

FlagShortDescription
--method-mThe installation method that was used; curl, npm, pnpm, bun, brew

Global Flags

The Lunos CLI takes the following global flags.

FlagShortDescription
--help-hDisplay help
--version-vPrint version number
--print-logsPrint logs to stderr
--log-levelLog level (DEBUG, INFO, WARN, ERROR)
--pureRun without external plugins

Environment variables

Lunos can be configured using environment variables.

VariableTypeDescription
OPENCODE_AUTO_SHAREbooleanAutomatically share sessions
OPENCODE_GIT_BASH_PATHstringPath to Git Bash executable on Windows
OPENCODE_CONFIGstringPath to config file
OPENCODE_TUI_CONFIGstringPath to TUI config file
OPENCODE_CONFIG_DIRstringPath to config directory
OPENCODE_CONFIG_CONTENTstringInline json config content
OPENCODE_DISABLE_AUTOUPDATEbooleanDisable automatic update checks
OPENCODE_DISABLE_PRUNEbooleanDisable pruning of old data
OPENCODE_DISABLE_TERMINAL_TITLEbooleanDisable automatic terminal title updates
OPENCODE_PERMISSIONstringInlined json permissions config
OPENCODE_DISABLE_DEFAULT_PLUGINSbooleanDisable default plugins
OPENCODE_DISABLE_LSP_DOWNLOADbooleanDisable automatic LSP server downloads
OPENCODE_ENABLE_EXPERIMENTAL_MODELSbooleanEnable experimental models
OPENCODE_DISABLE_AUTOCOMPACTbooleanDisable automatic context compaction
OPENCODE_DISABLE_CLAUDE_CODEbooleanDisable reading from .claude (prompt + skills)
OPENCODE_DISABLE_CLAUDE_CODE_PROMPTbooleanDisable reading ~/.claude/CLAUDE.md
OPENCODE_DISABLE_CLAUDE_CODE_SKILLSbooleanDisable loading .claude/skills
OPENCODE_DISABLE_MODELS_FETCHbooleanDisable fetching models from remote sources
OPENCODE_DISABLE_MOUSEbooleanDisable mouse capture in the TUI
OPENCODE_FAKE_VCSstringFake VCS provider for testing purposes
OPENCODE_CLIENTstringClient identifier (defaults to cli)
OPENCODE_ENABLE_EXAbooleanEnable Exa web search tools
OPENCODE_ENABLE_PARALLELbooleanEnable Parallel web search tools
OPENCODE_SERVER_PASSWORDstringEnable basic auth for serve/web
OPENCODE_SERVER_USERNAMEstringOverride basic auth username (default lunos)
OPENCODE_MODELS_URLstringCustom URL for fetching models configuration

Experimental

These environment variables enable experimental features that may change or be removed.

VariableTypeDescription
OPENCODE_EXPERIMENTALbooleanEnable the experimental umbrella flag
OPENCODE_EXPERIMENTAL_ICON_DISCOVERYbooleanEnable icon discovery
OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECTbooleanDisable copy on select in TUI
OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MSnumberDefault timeout for bash commands in ms
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAXnumberMax output tokens for LLM responses
OPENCODE_EXPERIMENTAL_FILEWATCHERbooleanEnable file watcher for entire dir
OPENCODE_EXPERIMENTAL_OXFMTbooleanEnable oxfmt formatter
OPENCODE_EXPERIMENTAL_LSP_TOOLbooleanEnable experimental LSP tool
OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHERbooleanDisable file watcher
OPENCODE_EXPERIMENTAL_EXAbooleanEnable experimental Exa features
OPENCODE_EXPERIMENTAL_LSP_TYbooleanEnable TY LSP for python files
OPENCODE_EXPERIMENTAL_PLAN_MODEbooleanEnable plan mode
OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTSbooleanEnable background subagent tasks
OPENCODE_EXPERIMENTAL_EVENT_SYSTEMbooleanEnable experimental event system
OPENCODE_EXPERIMENTAL_NATIVE_LLMbooleanEnable native LLM request path
OPENCODE_EXPERIMENTAL_PARALLELbooleanEnable parallel web search execution
OPENCODE_EXPERIMENTAL_SCOUTbooleanEnable Scout subagent
OPENCODE_EXPERIMENTAL_WORKSPACESbooleanEnable workspace support