Configuration

Moon CLI reads two families of files: its own settings (moon.json), written by the moon blur and moon guard commands, and the agent configuration (opencode.json, tui.json, and folders of skills, commands and instructions). Each exists in a personal version that applies to all your projects, and the agent configuration also exists at the project level.

Locations#Link to the Locations section

File or folder	macOS, Linux, WSL	Windows
Moon CLI settings	~/.config/moon/moon.json	%USERPROFILE%\.config\moon\moon.json
Personal agent configuration	~/.config/moon/opencode.json	%USERPROFILE%\.config\moon\opencode.json
Agent interface	~/.config/moon/tui.json	%USERPROFILE%\.config\moon\tui.json
Personal instructions	~/.config/moon/AGENTS.md	%USERPROFILE%\.config\moon\AGENTS.md
Personal skills	~/.claude/skills/, ~/.agents/skills/	%USERPROFILE%\.claude\skills\, %USERPROFILE%\.agents\skills\
Personal commands	~/.config/moon/commands/	%USERPROFILE%\.config\moon\commands\

The agent configuration also accepts the names opencode.jsonc (with comments) and config.json in the same folder. If you set XDG_CONFIG_HOME, its value replaces the ~/.config folder.

In a project, the agent reads the following files, between the Git repository root and the opened folder:

Moon CLI settings (moon.json)#Link to the Moon CLI settings (moon.json) section

{
  "blur": {
    "mode": "secrets",
    "projects": { "/home/alice/code/client": "redact" },
    "allow": ["<SHA-256 fingerprint of a value>"]
  },
  "guard": { "enabled": true },
  "updates": { "auto": true }
}

A repository cannot change this file, and the agent’s tools cannot access it. An unreadable file is ignored: all settings then go back to their default values.

Agent configuration (opencode.json)#Link to the Agent configuration (opencode.json) section

The same format is used for the personal file and for a project’s. Example project file:

{
  "model": "moonai/anthropic/claude-haiku-4.5",
  "instructions": ["guides/conventions.md"],
  "permission": {
    "bash": {
      "*": "ask",
      "npm test": "allow"
    }
  },
  "mcp": {
    "context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "enabled": true }
  }
}

A value can reuse an environment variable with {env:NAME}, or the content of a file with {file:path} (path relative to the configuration file, or starting with ~/). Use them to avoid writing a secret in clear text in a versioned file.

Moon CLI does not let any model provider other than Moon AI through: a provider or enabled_providers key that would add one is ignored, and session sharing stays off.

Order of precedence#Link to the Order of precedence section

Agent configuration#Link to the Agent configuration section

Sources are merged in this order; a key defined lower down replaces the same key defined higher up.

1. Your personal configuration (~/.config/moon/opencode.json).
2. The session settings Moon CLI sets at every launch: the Moon AI provider and its models, the Auto model, a small model for background tasks, automatic compaction, default permissions.
3. The project configuration, if you approved it: the opencode.json files from the repository root down to the opened folder, then the .opencode/ folders.
4. The configuration managed by the computer’s administrator (see below).
5. The keys locked by Moon CLI: Moon AI as the only provider, sharing off, no self-update of the agent.

instructions lists add up from one source to the next. A consequence of this order: in your personal configuration, the model, small_model, compaction.auto and compaction.prune keys and the edit, bash, webfetch and websearch rules are replaced by Moon CLI’s. To change them, use a project configuration.

Moon CLI settings#Link to the Moon CLI settings section

Default model#Link to the Default model section

At launch, the agent picks its model in this order:

1. the -m moonai/<id> (or --model) option of moon or moon run;
2. the model key of the approved project configuration;
3. Auto, Moon CLI’s default model.

The model chosen in the agent with /models applies to the current session; at the next launch, Moon CLI goes back to the rule above. moon models lists the available IDs, already prefixed with moonai/.

moon models
moon -m moonai/anthropic/claude-haiku-4.5

Choosing a model and cost levels are covered in Workspaces and models.

Permissions#Link to the Permissions section

By default, the agent asks for your approval before it:

The agent’s file tools never have access to the Moon CLI state folder (your session) or to ~/.config/moon.

Three ways to reduce prompts:

• The session mode: edits accepted or automatic approval, with ShiftTab, /modifications or /auto. See Permission modes.
• “Toujours autoriser” (always allow) on a request, when it offers it.
• Rules in the project configuration, under the permission key.

A rule is allow (no prompt), ask (prompt) or deny (refused). For bash, a rule can target a command pattern, where * stands for any sequence of characters; when several patterns match, the last rule written wins.

{
  "permission": {
    "bash": {
      "*": "ask",
      "npm test": "allow",
      "git status": "allow",
      "rm *": "deny"
    },
    "webfetch": "deny",
    "context7_*": "allow"
  }
}

One exception since Moon CLI 0.5.0: git push and pull request creation written as such are asked even when an allow rule (for example "git *": "allow") covers them; a deny rule refuses them. See Commands that publish.

Moon Blur#Link to the Moon Blur section

You set the mode with moon blur (saved in moon.json), for one terminal with MOON_BLUR_MODE, and during a session with /blur.

moon blur redact          # all your projects
moon blur strict --here   # this folder only

Modes, detection and allowed values: Moon Blur in Moon CLI.

Moon Guard#Link to the Moon Guard section

Moon Guard is off by default. moon guard on turns it on for the next launches (guard.enabled key), MOON_GUARD=on for a single launch. See Moon Guard.

MCP servers#Link to the MCP servers section

/mcp writes servers to your personal configuration (~/.config/moon/opencode.json). You can also declare them by hand, in that file or in a project’s, under the mcp key:

Adding, connecting and securing servers: MCP servers in Moon CLI.

Skills#Link to the Skills section

A skill is a folder that contains a SKILL.md file: a name and a description in the header, then the instructions, and possibly scripts. The agent loads it when the task calls for it.

In the agent, /skills lists the available skills; each one can also be called directly with /<name>.

Instruction files#Link to the Instruction files section

Instruction files go with every call to the model. The agent reads:

1. a single personal instruction file: ~/.config/moon/AGENTS.md, otherwise ~/.claude/CLAUDE.md;
2. in the approved project, the AGENTS.md files from the repository root down to the opened folder. If there are none, the CLAUDE.md files, otherwise the CONTEXT.md files;
3. the files listed by the instructions key;
4. during the session, the AGENTS.md of a subfolder whose files the agent reads.

Each file is cut off beyond 40 KB (the beginning is kept), and the total is limited to 100 KB. At launch, Moon CLI flags any file over 40 KB with an estimate of the tokens sent with each call. /init creates or updates the project’s AGENTS.md.

Custom commands#Link to the Custom commands section

A Markdown file in ~/.config/moon/commands/ (for you) or .opencode/commands/ (for the project) becomes an agent / command, named after the file.

---
description: Runs a module's tests and explains the failures
---
Run the tests of the $ARGUMENTS module, then summarize each failure and suggest a fix.

/test-module payments sends the text to the model, replacing $ARGUMENTS with payments; $1, $2 refer to the arguments one by one. The header also accepts agent (the agent that runs the command), model and subtask (true: run by a sub-agent).

Agent interface (tui.json)#Link to the Agent interface (tui.json) section

{
  "keybinds": {
    "leader": "ctrl+x",
    "session_new": "<leader>n"
  },
  "mouse": true,
  "diff_style": "auto"
}

You choose the theme with /themes. The list of default shortcuts is in Keyboard shortcuts.

Configuration managed by the administrator#Link to the Configuration managed by the administrator section

On a company computer, the administrator can enforce an agent configuration, applied after the person’s and the project’s:

System	File
Linux	/etc/moon/opencode.json
macOS	/Library/Application Support/moon/opencode.json, or a device management profile (domain ai.realmoon.moon.managed)
Windows	C:\ProgramData\moon\opencode.json

The folder and the file must belong to the computer’s administration (root, with no write access for the group or others, on Linux and macOS; Administrators or SYSTEM on Windows); otherwise they are ignored.

Environment variables#Link to the Environment variables section

Moon CLI#Link to the Moon CLI section

Installation#Link to the Installation section

Details: Installation options.

Network#Link to the Network section

Agent#Link to the Agent section

The agent receives your environment, except the MOON_* and OTEL_* variables. Of its own variables, only these are passed to it:

The other variables of your environment, such as GITHUB_TOKEN, stay visible to the agent and to the commands it runs.

See also#Link to the See also section

• Command reference
• Using the agent
• Installation file locations