Choose the Right Safeguard CLI Permission Mode for Each Task

Pick the Safeguard CLI permission mode by how much the task can break. Use Plan to explore a repository without changing it, Ask for unfamiliar or sensitive work, Accept edits for multi-file refactors, Auto for everyday fixes and Strict for CI. Keep the --yolo flag for throwaway sandboxes, never for a machine you care about.

This guide walks through each mode with real commands, shows how to switch between them in the middle of a session, and covers what happens when you approve from the desktop app or your phone instead of the terminal.

What you will have at the end:

• A clear rule for which of the five modes to use for each kind of task.
• The commands to set a mode before a session starts, change it during a session and lock it down for CI.
• A habit of narrowing any mode with allow and deny rules, so routine commands stop interrupting you and dangerous ones never run.
• A safety net: checkpoints for file edits, git for everything else, and a scan before you merge.

You do not have to give up the AI plan you already use to follow along. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server and ask about your findings from the chat you already use.

The five modes at a glance

The Safeguard CLI assistant has tools for your local files and for your Safeguard data. Reading is low risk. Writing a file, editing code and running a command change things, so the permission mode decides which of those run straight away and which wait for you.

Type /permissions in the interactive terminal (CLI v11.11.0, checked 21 October 2026) and you get five modes:

The command line uses its own names for the same settings. safeguard --help lists --permission-mode (short form -a) with the values supervised, edits, plan, guarded, strict and autonomous. In practice:

• supervised is Ask.
• edits is Accept edits.
• plan is Plan.
• guarded is Auto.
• strict is Strict.
• autonomous approves everything. The help text says --dangerously-skip-permissions allows autonomous mode outside a sandbox runner, and --yolo is an alias for that flag.

Two other surfaces work differently. The Safeguard browser extension has its own setting: Ask, Auto or Yolo. And when you send work to a computer from the desktop or phone app, each command and file edit waits for you to approve it there.

How to set and switch modes

You can choose a mode in three places. Use whichever fits the moment.

1. Inside a session. Run safeguard with no arguments to open the interactive terminal, then type /permissions and pick a mode. The /status command shows the current approval mode along with your user, tenant and runner.

2. When you start a session. Pass the flag so the session opens in the mode you want:

   # Look around a new repository without changing anything
   safeguard -a plan
   
   # Start a refactor where file edits should not interrupt you
   safeguard --permission-mode edits
   

3. For a single non-interactive turn. safeguard exec runs one assistant turn and exits. Its default mode is strict, so nothing is asked and anything not pre-approved is denied. You can loosen it for local scripts:

   # Read-only question from a script, nothing changes
   safeguard exec -a plan "list the dependencies in package.json that have known vulnerabilities"
   

If something starts going the wrong way, press esc. The docs describe it as interrupting whatever is running without exiting, so you can switch mode and try again.

To see a mode in a real session, click through the recorded CLI demo in Try it yourself at the end of this guide.

Match the mode to the task

Here is how the modes map to work you probably do every week. Each one comes with the commands to run it.

Exploring a repository you have never seen: Plan

You joined a team, inherited a service or are reviewing a vendor's code. You want answers, not changes.

1. Clone the repository and change into it.
2. Start in Plan mode: safeguard -a plan.
3. Ask broad questions: "explain how requests flow through this service", "which packages does this project depend on directly", "how many critical vulns do we have".
4. Ask for a plan: "plan the steps to upgrade the vulnerable dependencies, with the files each step touches".
5. Copy the plan with /copy into a ticket or a pull request description.

Plan mode reads and plans only; nothing is changed. That makes it the right place to start whenever you are unsure what a change will touch.

Fixing a vulnerable dependency in a repository you know: Auto

This is the daily case and the reason Auto is the default. Read-only commands such as listing files run straight away. Installing packages and running scripts ask.

1. Open the project and start a session with safeguard.

2. Run /scan . to scan the current folder.

3. Ask in plain language: "fix the lodash CVE in this repo".

4. Approve the manifest edit, then the install and the test run when they come up.

5. Check the result yourself before you commit:

   git diff --stat
   npm test
   

npm test runs whatever the test script in package.json defines, so you are checking the same thing the assistant ran. If the project uses a lockfile in CI, npm ci is a useful extra check: the npm docs say it errors out instead of updating the lockfile when package.json and the lockfile disagree.

A refactor across many files: Accept edits

Renaming a function used in forty places or moving a module means dozens of edits. Approving each one teaches you to press y without reading, which is worse than not asking.

1. Commit or stash your own work first so the assistant's changes stand alone:

   git stash push -m "my work before the refactor"
   

2. Start in Accept edits: safeguard -a edits.

3. Describe the change precisely: "rename validateCard to validatePaymentCard everywhere in src and update the imports".

4. Let the edits run. Read-only commands also run; anything else, such as a build or test command, still asks.

5. Review the whole change as one diff with git diff, then run your tests.

6. Bring your own work back with git stash pop when you are done.

The trade is simple: you give up per-edit prompts and gain one careful review of the full diff. Because each file the assistant writes or edits is snapshotted first, checkpoints are especially useful in this mode (more on that below).

Sensitive code or a task you have never tried: Ask

Payment logic, authentication, deployment scripts and anything near credentials deserve a human look at every change. Use Ask.

1. Start with safeguard -a supervised, or switch with /permissions mid-session.
2. Reads run, so the assistant can still look around freely.
3. Every edit and every command stops for your answer. Read each one before you press y.

Ask is also the right mode for your first week with the CLI. Watching what it wants to do, step by step, is the fastest way to learn when you can trust a looser mode.

Continuous integration: Strict

A CI job has nobody at the keyboard, so a prompt would just hang. Strict runs only what you pre-approved and refuses the rest. safeguard exec already defaults to it.

Pre-approve narrowly with allow rules. The help text gives the syntax as policy.yaml rules such as Bash(go test:*):

safeguard exec --permission-mode strict \
  --allowedTools 'Bash(npm test:*)' \
  --output-format json \
  "summarise the critical findings in this repository"

Two details from the exec help matter in pipelines. It refuses to run outside a git repository, because there would be no way to undo what it changes (--skip-git-repo-check overrides that, and you should rarely need it). And --max-budget-usd ends the turn once a set amount has been spent, which is a sensible ceiling for scheduled jobs.

For scanning in a pipeline, safeguard ci scan is the dedicated command. Its help says it authenticates with a secret key stored as the CI secret SAFEGUARD_API_KEY. In GitHub Actions you pass a secret to a step through the secrets context:

- name: Safeguard scan
  env:
    SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
  run: safeguard ci scan --local --wait --fail-on high

With --local the scan runs on the CI runner and only the results are uploaded, never the source. The full setup, including the exec step, is in our guide to safeguard exec in CI.

A throwaway sandbox: --yolo, and only there

--yolo approves everything. It exists for disposable environments: a fresh container, a cloud sandbox, a VM you will delete in an hour. Do not use it on your laptop, on a machine with production credentials, or in a repository with uncommitted work you care about.

If you want speed without giving up the prompt for commands, Accept edits is almost always the better answer.

Approve from the desktop app or your phone

A CLI session is live. It shows in the web app, the desktop app and the phone app, and those devices can send work to a computer running the CLI. That changes how approvals feel: you can start a long task at your desk and answer prompts from somewhere else.

From the desktop app:

1. Open the conversation list. Your CLI session appears there.
2. Check the "2 connected" indicator, which shows the computer, the browser and Safeguard cloud.
3. Ask for work on your computer. The app asks which computer and which folder.
4. Pick the folder.
5. Approve or Deny each command and file edit as it comes up.

The recorded desktop session ends with the upgrade done and the tests passing:

Click through it at your own pace, or open it full screen.

The phone works the same way, with one extra choice. On Android, "Work on my computer" picks a computer running the CLI and a folder. When a command needs approval it waits on the phone with three buttons: Allow once, Allow for turn or Deny.

• Allow once approves this one command. Use it by default.
• Allow for turn lets the rest of the current turn go ahead. Use it only after you have read the first request and the rest of the turn is clearly the same kind of work.
• Deny stops that action.

This recorded Android session shows the same flow end to end, finishing with the answer that the tests passed:

Click through it at your own pace, or open it full screen.

A small screen makes it tempting to tap without reading. If you cannot read the full command on your phone, deny it and look at it at your desk. Setup for each app is in the desktop app guide and the Android guide.

Narrow any mode with allow and deny rules

Modes are coarse. Rules let you tune one without switching to another. The safeguard --help output lists these flags, and they work with both the interactive terminal and exec:

A few patterns that work well:

• Auto plus an allow rule for your test command. Tests run without a prompt; installs and everything else still ask.
• Any mode plus a deny rule for secrets folders. --disallowedTools 'Read(~/.ssh/**)' keeps keys out of reach even in a loose mode.
• --restricted for a pure question session. Useful on a shared machine when you only want answers.
• --sandbox on Linux for long Accept edits runs. Writes outside the workspace are blocked by the kernel, not just by a prompt.

If you already use Claude Code, Codex or OpenCode, note that safeguard other-agents is on by default. Its help says it reads those tools' agents, skills, custom commands, MCP servers, hooks, permissions and instructions below Safeguard's own. Run safeguard other-agents off if you want only Safeguard's files to apply. To convert a setup instead, safeguard import claude or safeguard import codex turns it into Safeguard configuration.

Your safety net: checkpoints, git and a scan

No mode is perfect, so plan for the change you did not want.

Checkpoints cover file edits. The checkpoints help says files the agent writes or edits are snapshotted before each change, and these are the same checkpoints /rewind uses:

safeguard checkpoints list --session <id>
safeguard checkpoints restore <checkpoint> --session <id> --dry-run
safeguard checkpoints restore <checkpoint> --session <id> --files-only

--dry-run shows what would change as a diff. A restore can itself be undone, because the state it overwrites is kept as a new checkpoint.

Checkpoints do not cover shell commands. The same help text is explicit: anything a shell command writes is not snapshotted. That is why it pays to keep commands behind a prompt. An npm install that rewrites node_modules, or a script that deletes files, is only undone by git or a backup.

Git covers the rest. Start risky sessions from a clean tree. git stash push saves your local modifications and returns the working directory to HEAD; git stash pop brings them back.

A scan covers what a diff hides. A one line manifest change can pull in many transitive packages. Before you commit, run safeguard review to review working-tree changes for correctness and security, or safeguard review --base main to compare against a branch. Then /scan . or safeguard scan --dir . for the dependency picture. Our guide to reviewing AI-generated code before merge goes further.

Do the work properly with the Safeguard CLI

The Safeguard CLI scans code, container images and SBOMs on your own machine, sends only the results to the platform, and includes an assistant that can write and fix code. Permission modes are what let you hand that assistant real work without handing over control.

Install

On macOS and Linux:

curl -fsSL https://cli.safeguard.sh/install | bash
safeguard --version

On Windows, in PowerShell:

irm https://cli.safeguard.sh/install.ps1 | iex

It is a single static binary with no Node, Python or JVM to install. Builds exist for macOS, Linux and Windows on x86_64 or arm64 (Windows on x86_64 only). The macOS install guide walks through it step by step.

First session

1. Run safeguard to open the interactive terminal.
2. Type /login to sign in through your browser.
3. Type /permissions and look at the five modes. Leave it on Auto for now.
4. Run /scan . on a project you know.
5. Ask "how many critical vulns do we have", then "fix the lodash CVE in this repo" if that applies.
6. Use /model to see or switch the model, @ to attach a file from the folder you started in, and /resume to pick the session up later.

Use your own model

/model shows or switches the AI model. To connect the Claude, ChatGPT or Codex plan you already have, see /model and the CLI docs.

What stays on your machine

When the local runner runs platform scan jobs, your source code never leaves the machine; only SBOMs and findings are uploaded. Policies and gates are evaluated in the platform, not by the CLI, so the gate that blocks a release is the same one for every developer.

Download the CLI and the apps from safeguard.sh/download.

Troubleshooting

The assistant asks about a command I thought Auto would allow. Auto runs read-only commands and what your policy allows. Anything else asks. Add an allow rule such as --allowedTools 'Bash(npm test:*)' for routine commands you trust.

exec does nothing in CI. Strict refuses anything not pre-approved. Read the output for refused actions and add narrow allow rules, rather than switching to autonomous.

exec refuses to start. It will not run outside a git repository. Check out the repository in the job, or run it from the right folder with -C path.

A restore did not bring back a file. If a shell command wrote it, no checkpoint exists. Use git (git diff shows what changed, git stash pop brings back stashed work) or your backup.

My phone shows a request I do not recognise. Deny it. Then open the conversation on your desktop and read the full transcript before continuing.

Something else looks wrong. Run safeguard doctor. It checks everything the agent depends on, changes nothing, and prints problems in the order that matters.

Common mistakes

• Leaving Auto on for sensitive code. Auto is a good default for a repository you know. For payment, auth or deployment code, switch to Ask.
• Using --yolo to make prompts go away. If prompts are too frequent, use Accept edits or an allow rule. Keep --yolo for disposable sandboxes.
• Approving "Allow for turn" on the first request. Read the first one, then decide whether the rest of the turn is the same kind of work.
• Trusting checkpoints for commands. They cover file edits only.
• Skipping the scan because the tests passed. Tests check behaviour, not whether a new transitive package has a known vulnerability.
• Wide allow rules in CI. Bash(*) defeats the point of Strict. Allow the exact commands the job needs.

FAQ

What is the default permission mode in the Safeguard CLI?

Auto. Read-only commands and what the policy allows run; anything else asks. safeguard exec is different: it defaults to Strict.

Which mode should I use when I just want answers?

Plan. It reads and plans only and changes nothing. --restricted is a stricter option that removes writes, the shell and network access from the tool set.

Is Accept edits safe?

It runs file edits in the current folder and read-only commands without asking, while other commands still ask. With a clean git tree and checkpoints, edits are easy to undo. Review the full diff before you commit.

When should I use the --yolo flag?

Only in throwaway sandboxes such as a disposable container or VM. It approves everything, including commands that checkpoints cannot undo.

Can I approve actions from my phone?

Yes. A CLI session shows on the phone app, and when work is sent to a computer running the CLI, each command waits for Allow once, Allow for turn or Deny.

Do the browser extension's modes match the CLI's?

No. The browser extension uses Ask, Auto or Yolo. The CLI has Ask, Accept edits, Plan, Auto and Strict, plus the --yolo flag.

Can I use my own Claude, ChatGPT or Codex plan?

Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. See /model and the CLI docs to connect it. You can also connect Claude or ChatGPT to the Safeguard MCP server.

Does the CLI enforce my organisation's release gates?

No. Policies and gates are evaluated in the platform. The CLI runs scans and sends results there, and safeguard ci scan --fail-on-gate lets a pipeline wait for a gate's result.

Try it yourself

This recorded session on a sample project, payments-api, installs the CLI with the curl command (checksum verified), checks safeguard --version and opens the terminal. Asked to "fix the lodash CVE in this repo", the assistant reads the finding, files and advisory, then asks before each command (press y or n). It edits package.json to lodash 4.17.21, runs npm install and npm test with approval, and prints a summary with a suggested commit message, pushing nothing. Then it opens /permissions, /model and /scan ..

Click through it at your own pace, or open it full screen.

Then download the CLI, run one task in Plan mode and the next in Auto, and keep the CLI docs open.

Quick check

Sources

• Safeguard CLI docs
• Safeguard CLI interactive terminal docs
• Safeguard CLI slash commands docs
• Safeguard download page
• npm ci, npm docs
• npm test, npm docs
• git stash, Git documentation
• git diff, Git documentation
• Using secrets in GitHub Actions, GitHub docs

Last reviewed: 21 October 2026.