Using the agent

Once you are signed in, you use Moon CLI from your project folder. You describe the task; the agent reads the code, proposes changes and runs commands, with your approval.

Start the agent in a project#Link to the Start the agent in a project section

cd my-project
moon

You can also point it at another folder: moon ../other-project.

At startup, the terminal shows a summary: your workspace and its plan, the selected model, the Moon Blur mode and your usage (5-hour session, week, month). The usage bar turns amber from 75% and red from 90%. The agent interface then opens.

The agent works in this folder, inside the Git repository that contains it. It never loads configuration or instructions located above the repository root.

At the end of the session, Moon CLI tells you how many values Moon Blur masked.

Home folder and drive root#Link to the Home folder and drive root section

Started in your home folder or at the root of a drive, the agent would scan every file and startup could take several minutes. Moon CLI warns you and asks “Continuer quand même ? [o/N]” (continue anyway?). Move to a project folder instead.

To stop seeing this warning (in a script, for example), set MOON_ALLOW_BROAD_DIR=1.

A repository’s configuration#Link to the A repository’s configuration section

A repository can contain agent configuration: it can launch plugins, add MCP servers or skills, or allow commands without confirmation. A booby-trapped cloned repository could use it to take control. Moon CLI only loads it with your approval.

Files involved, in every folder between the opened folder and the repository root:

• opencode.json, opencode.jsonc, tui.json, tui.jsonc;
• the .opencode/, .claude/skills/ and .agents/skills/ folders.

If any of them exists, Moon CLI lists them and asks “Faire confiance à cette configuration ? [o/N]” (trust this configuration?).

• The question comes back if the content of these files changes.
• Beyond 5,000 files or 200 MB, the configuration cannot be fully checked: the question comes back at every launch.
• Without an interactive terminal, the repository’s configuration is ignored, unless MOON_TRUST_PROJECT=1 is set.
• A repository with none of these files does not trigger the question: its instruction files are read normally.
• To forget all your approvals, delete the trusted-projects.json file from the state folder (see File locations).

Instruction files#Link to the Instruction files section

The agent reads your project’s AGENTS.md files (or CLAUDE.md, then CONTEXT.md, if there is none) and your personal instruction file (~/.config/moon/AGENTS.md, or ~/.claude/CLAUDE.md if there is none). They go with every call to the model, so they count against your usage limit. Above 40 KB, Moon CLI shows a warning at startup with an estimate of the tokens sent with each call: keep these files short.

/init creates or updates the project’s AGENTS.md. Reading order and limits: Instruction files.

The interface#Link to the The interface section

• Header: your workspace and the gauge of your usage limit.
• Status bar: folder, Git branch, Moon Blur mode and how full the context is.
• Input panel: your message and the active permission mode.
• Actions: each action of the agent is summed up on one line.
• Permissions and questions: choices are numbered; answer with the 1, 2, 3 keys.
• Moon, the Moon AI mascot, follows the session: it thinks, acts, waits for your approval, cheers at the end of a turn or looks worried about an error.

/themes changes the colors of the whole interface.

Writing to the agent#Link to the Writing to the agent section

The build and plan agents#Link to the The build and plan agents section

Two main agents are available. Tab or /agents switches between them.

To explore the code, the agent can hand part of the work to a sub-agent, which uses an economical model.

Permission modes#Link to the Permission modes section

By default, the agent asks for your approval before it changes a file, runs a command, reads a web page or searches the web, and before it uses an MCP server’s tool. Some requests also offer to always allow (for a website, for example).

Three modes change this behavior:

• ShiftTab goes from Ask to Accept edits, then to Autonomous if you have already accepted it in this session, then back to Ask.
• /modifications turns Accept edits on or off.
• /auto turns Autonomous mode on or off. The first time in a session, Moon CLI asks “Passer en mode Autonome ?” (switch to Autonomous mode?) and shows the warning below.
• moon --auto starts directly in Autonomous mode, with no confirmation.

Requests already on screen when you change mode still wait for your answer.

In the terminal, every session starts in Ask mode, unless you use moon --auto. In Code, on the web with moon rc as in Moon Desktop, “Keep the chosen mode” makes the next sessions of a folder start in the last mode you chose (Moon CLI 0.5.4): see Keep the chosen mode.

In Ask and Accept edits modes, git push and pull request creation written as such (Moon CLI 0.5.0), and the deletions Moon CLI recognizes (Moon CLI 0.6.0), are always asked: see Commands that publish and Deletions. So are the writes of your Moon AI connectors: see Moon AI connectors in Moon CLI.

To allow certain commands permanently in a project, use permission rules: see Permissions.

When your organization does not allow Autonomous mode#Link to the When your organization does not allow Autonomous mode section

A managed organization can prevent its members from using Autonomous mode. With Moon CLI 0.5.4 or later, in a workspace of that organization:

• ShiftTab and /auto no longer offer it; Accept edits is still allowed.
• moon --auto starts in normal mode and says so: “Votre organisation ne permet pas le mode Autonome : Moon CLI démarre en mode normal.” (your organization does not allow Autonomous mode: Moon CLI starts in normal mode).
• moon run denies permission requests as it does without --auto, and says so.
• In Code, “Autonomous” is no longer offered, and an Autonomous mode kept for a folder is not applied.
• As long as Moon CLI could not read the rule, it does not grant this mode: “La règle de votre organisation sur le mode Autonome n’a pas pu être lue : Moon CLI démarre en mode normal.” (your organization’s rule on Autonomous mode could not be read: Moon CLI starts in normal mode).

The rule does not apply to Moon CLI started with an API key (MOON_API_KEY). See Moon CLI Autonomous mode.

Commands that publish#Link to the Commands that publish section

Since Moon CLI 0.5.0, a command that can publish your code outside your computer is asked every time in Ask and Accept edits modes, and since Moon CLI 0.6.1 in Autonomous mode too (as it was up to 0.5.6; in 0.6.0, it went through without asking):

• git push, in its written forms (git -C folder push, sudo git push, an alias defined on the same line…);
• creating a pull request: gh pr create and its equivalents for other forges;
• anything that changes where and how a push will go: git remote add or set-url, a push URL or a git alias set with git config;
• since Moon CLI 0.6.1, a deployment or an upload to a server (vercel, netlify deploy, firebase deploy, wrangler deploy, scp, rsync or rclone to another machine, curl sending data to an address that is not on your computer, kubectl apply, terraform apply…), publishing a package (npm publish, cargo publish…) and whatever gh or glab writes to GitHub or GitLab (gh issue create, gh pr merge, gh release create, gh api writes…).

Reading from the network is not publishing: curl or wget reads, a download, npm install, git fetch and git pull, gh api reads, scp that copies a file back to your machine. In Autonomous mode, Moon runs them without asking.

An allow rule in the configuration, or an earlier “Toujours autoriser” (always allow), changes nothing here; a deny rule refuses the command. When in doubt, Moon asks: a command that looks like a push is asked.

• The request is titled “Commande shell qui publie” (shell command that publishes). It shows the command, says where the push goes (the remote repository’s address, without credentials) and which commits are sent, and only offers “Autoriser une fois” (allow once) and “Refuser” (deny).
• Since Moon CLI 0.6.1, these commands are asked in Autonomous mode too (moon --auto included); in 0.6.0, they went through without asking.
• moon run, with nobody there to answer, refuses these commands and explains why, with or without --auto.
• On the Code page, the same request appears as a card: see Publish: git push and PR.

Deletions#Link to the Deletions section

Since Moon CLI 0.6.0, a deletion that Moon CLI recognizes is always asked in Ask and Accept edits modes: rm, del or Remove-Item, a file emptied or overwritten, git clean, git reset --hard, git checkout on files, a patch that removes a file, and Moon’s delete tool. A “Toujours autoriser” (always allow) rule changes nothing here.

• The request, in red, lists the files that will go and says what will happen: “Les fichiers vont à la corbeille.” (the files go to the trash) for Moon’s delete tool, “Cette commande peut supprimer ou écraser pour de bon : rien ne passe par la corbeille.” (this command can delete or overwrite for good: nothing goes through the trash) for a command. It only offers “Autoriser une fois” (allow once) and “Refuser” (deny).
• Moon prefers its delete tool, which moves files to the system trash (Windows, macOS, Linux) instead of erasing them. The .git folder is off limits to it, except in Autonomous mode.
• In Autonomous mode, deletions go through without asking, even outside the project; Moon CLI notes them in the terminal.
• moon run without --auto refuses them and suggests moon run --auto to accept them automatically.
• In Code, the same request appears as a card, and deletions stay listed in the rail, with “Restore”: see Deletions.

Moon’s questions#Link to the Moon’s questions section

When a decision is yours to make, Moon can ask you a question while it works, with answers to pick from or an answer to type. Answering authorizes nothing: every action is still asked. In Code, the question appears as a card: see Moon’s questions.

Background commands#Link to the Background commands section

Since Moon CLI 0.5.1, when Moon starts a command that runs indefinitely, such as a development server (npm run dev) or a test watcher, it leaves it in the background and takes back control after a few seconds, with its first lines. Before, it was cut off after two minutes, or started outside any tracking (with & or Start-Process, for example).

• The request is titled “Commande shell, en arrière-plan” (shell command, in the background). It explains, in French, that the command keeps running after this step, with everything it starts, until it ends, is stopped, or Moon CLI closes; that anything it opens, such as a browser, may close with it; and that /fond shows or stops it. It follows the same rules as any command: the permission mode, Moon Guard and commands that publish.
• /fond lists the background commands, the session’s first, with their status (“en cours depuis 3 min”, running for 3 min; “terminée (code 1)”, finished (code 1); “arrêtée par vous”, stopped by you…) and their last line. Enter on a running command stops it, along with everything it started: “Commande arrêtée, avec tout ce qu’elle avait lancé.” (command stopped, along with everything it had started).
• When they stop: when they end, when you stop them, or when you quit Moon CLI. Interrupting Moon (Esc twice) does not stop them, except in the first seconds after launch. With moon run --auto, they stop when moon run finishes.
• Moon can also read their output or stop them itself, for example to restart a server with other options.
• Limits: 8 background commands at a time per session, 16 for a single Moon CLI.
• On the Code page and in Moon Desktop, the “In progress” panel shows them with their last lines and stops them in one click: see Background commands.

Agent commands#Link to the Agent commands section

Type / in the agent to show the commands, or CtrlP for the palette. The most used:

Full list with aliases: Interface commands.

Task without the interface (moon run)#Link to the Task without the interface (moon run) section

For a one-off task, without opening the interface:

moon run "explain what the src/api folder does"
moon run --auto "add a test for the parse_date function"

moon "…" does the same thing: a first argument that is not an option, a command or an existing folder is treated as a task. Moon CLI prints the answer, then exits.

Nobody is there to answer permission requests: without --auto, every file change, command or web access is denied, and the terminal shows “permission demandée : … ; refus automatique” (permission requested: …; automatically denied). Reading and searching the code still work. With --auto, every request is accepted: since Moon CLI 0.6.0, that includes deletions and commands that publish (git push, pull request creation); from 0.5.0 to 0.5.6, the latter were still refused. A Moon AI connector write that Moon AI asks about in every mode (a payment, a bulk send) is refused, since nobody is there to approve it.

Whatever you send on standard input is added to the request: git diff | moon run "summarize these changes". All options: moon run.

In continuous integration#Link to the In continuous integration section

Without an interactive terminal, Moon CLI does not start a browser sign-in. Use a workspace API key (moai_org_…) in the MOON_API_KEY variable: nothing is written to disk, and the workspace and plan are those of the key.

export MOON_API_KEY="moai_org_..."
export MOON_TRUST_PROJECT=1      # only if the repository's configuration is safe
export MOON_GUARD=on             # blocks destructive commands
moon run --auto "run the tests and summarize the failures"

• --auto lets the agent run commands: keep it for a disposable environment.
• The key is removed from the environment of the agent and of the commands it runs.
• Automatic updates do not run in continuous integration.
• To create a workspace key, see Workspace keys.

See also#Link to the See also section

• Command reference
• Configuration
• Workspaces, models and usage limit