A good day with the Safeguard CLI follows one loop: open safeguard in the repository, scan, ask what needs attention, fix it with an assistant that asks before each edit or command, review the diff, scan again and push. The session stays live, so you can pick it up from the desktop app or your phone.
You keep the assistant you already pay for. 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. If you prefer to stay in the chat you already use, connect Claude or ChatGPT to the Safeguard MCP server and ask about your findings there.
What you will have at the end
By the end of this guide you will have:
- The Safeguard CLI installed, signed in and checked with
safeguard doctor. - A permission mode chosen on purpose for each kind of task, instead of whatever was on last time.
- A morning routine that tells you in a few minutes what changed in your dependencies.
- A way to fix findings and write code where every file edit and command waits for your yes or no.
- Checkpoints you can roll back to when an edit goes the wrong way.
- Your computer reachable from the desktop app and your phone, so you can approve work when you are not at the keyboard.
- A pre-push habit,
safeguard reviewplus a rescan, and a CI step that runs the same scan on every build.
You need a terminal, a Git repository, and a Safeguard account. Everything else is installed in the first section.
One time setup
Do this once per machine. It takes about ten minutes, most of it reading what each step prints.
1. Install the binary. On macOS and Linux:
curl -fsSL https://cli.safeguard.sh/install | bash
On Windows, in PowerShell:
irm https://cli.safeguard.sh/install.ps1 | iex
The CLI is a single static binary. There is no Node, Python or JVM to install first. It runs on macOS, Linux and Windows, on x86_64 or arm64, with Windows on x86_64 only. The download page notes that the install scripts verify checksums. If you want a longer walkthrough for your platform, see installing the Safeguard CLI on macOS.
2. Confirm the version.
safeguard --version
When we checked on 21 October 2026 this printed v11.11.0.
3. Run the doctor.
safeguard doctor
doctor checks the environment, your sign-in, the machine profile, policy and tools, and prints what is wrong in the order that matters. It changes nothing. Its exit code is 0 whenever the checks ran, so read the lines rather than the status.
4. Sign in. Move into a project and open the interactive terminal:
cd ~/code/payments-api
safeguard
Type /login, approve the session in the browser, and the terminal picks it up. /whoami shows who you are signed in as.
5. Pick a model. Type /model to see the current model and switch it. This is also where your own Claude, ChatGPT or Codex plan comes in; the CLI docs cover connecting one.
6. Choose a permission mode. Type /permissions. The modes are covered in the table below. Auto is the default and suits most days.
7. Bring your old setup, if you have one. If you have been using Claude Code or Codex, the CLI can read that setup:
safeguard import claude
safeguard import codex
safeguard other-agents
import converts a Claude Code or Codex setup into Safeguard configuration. other-agents shows whether the CLI also reads Claude Code, Codex and OpenCode configuration (agents, skills, custom commands, MCP servers, hooks, permissions and instructions) below its own. It is on by default.
8. Make the machine reachable from your other devices. This is optional, and it is what lets your phone send work here later:
safeguard runner install
It registers the runner as a per user login service (a LaunchAgent on macOS, a systemd user unit on Linux, a logon scheduled task on Windows). Nothing listens on a port; the runner only opens outbound HTTPS. safeguard runner uninstall undoes it.
9. Keep the binary current.
safeguard self-update --check
safeguard self-update
--check reports whether a new version exists and installs nothing. self-update verifies a signed release manifest and the archive digest before it swaps the binary, and keeps the previous one as safeguard.previous. It refuses to cross a major version unless you pass --allow-major.
The permission modes, side by side
/permissions in the interactive CLI offers five modes. Pick per task, not once per year.
| Mode | What runs on its own | What asks first | Good for |
|---|---|---|---|
| Ask | Reads | Every edit and every command | A repository you do not know yet |
| Accept edits | Edits in this folder and read-only commands | Other commands | A refactor you have already planned |
| Plan | Reads and planning only | Nothing changes | Thinking through a large change first |
| Auto (default) | Read-only commands and what the policy allows | Anything else | Day to day work |
| Strict | Pre-approved actions only | Nothing is asked; the rest is denied | CI |
There is also a --yolo flag that approves everything. Keep it for throwaway sandboxes only.
Morning: open the session and see what changed
The morning check is short. The point is to know what moved overnight before you start writing anything.
1. Update the branch and open the session.
cd ~/code/payments-api
git pull
safeguard
If you were in the middle of something yesterday, type /resume to pick up your last session in that folder. From a script you can do the same with safeguard -c, which continues the most recent session in this workspace.
2. Scan the folder.
/scan .
This builds an SBOM for the folder and matches it against vulnerability databases. Outside the interactive terminal the same scan is safeguard scan --dir ., which writes JSON results under ./output, including vuln.json and license.json.
3. Ask what needs attention. Plain language works. Some questions that earn their keep in the morning:
how many critical vulns do we have
what is new since my last scan in this folder, highest severity first
which of these findings are in direct dependencies, and which come in transitively
list the findings that have a fixed version available, with the version to move to
The assistant has tools for your local files and for your Safeguard data, and it picks whichever the question needs. You do not have to paste the scan output into the prompt.
4. Check a branch without uploading anything. Sometimes you want a quick look at a feature branch that should not appear in the platform yet. findings runs one scanner locally and prints the result in one normalized shape:
safeguard findings sca --dir .
safeguard findings sca --dir . --json
Nothing leaves the machine: no project is registered and no finding is uploaded, even when the CLI is signed in.
5. Check the inbox. If you sent yourself a link or a note from your phone last night, it is here:
safeguard inbox
safeguard inbox open ITEM_ID --copy
inbox lists the links, text, files and conversations your other devices sent to this CLI. inbox open prints or copies one item, and --browser opens a link in your system browser.
6. Decide the day's fixes. Set Plan with /permissions, then ask for a short plan before any edit:
propose the order to fix the high and critical findings, smallest change first
Plan reads and plans only, so nothing on disk changes while you decide. Switch back to Auto when you are ready to work.
Midday: write and fix code with approvals
This is where the CLI does the work. It writes code, not only scans it, and every change waits for your decision under the mode you picked.
1. Make a branch and a clean starting point.
git switch -c fix/morning-findings
git status
A clean tree makes every later diff easy to read and easy to undo.
2. Ask for the change with clear limits. Type @ to attach a file from the folder you started in, so the assistant reads the real file instead of guessing. Use ctrl+j for a new line inside one message.
@package.json
fix the lodash CVE in this repo
use the lowest version that fixes it, change only package.json and the lockfile,
then run npm install and npm test
3. Answer each prompt. The assistant reads the finding, the files and the advisory, then asks before each command. Press y to allow or n to refuse. If you refuse, say why in your next message, and it adjusts. Press esc to interrupt a running task without leaving the terminal.
4. Read the summary. A good answer lists every file it changed, the old and new versions, the commands it ran and their results. It should suggest a commit message and leave the push to you.
The recorded session below shows that exact loop on a sample project called payments-api, with test data. It installs with the curl command (checksum verified), runs safeguard --version, opens the interactive terminal with safeguard, and asks "fix the lodash CVE in this repo". The assistant reads the finding, files and advisory, then asks before each command (press y or n), 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. It pushes nothing. The session ends with /permissions, /model and /scan ..
Click through it at your own pace, or open it full screen.
5. Use checkpoints when an edit goes the wrong way. Files the assistant writes or edits are snapshotted before each change. Inside the session, /rewind goes back. From the shell you can look first and then restore:
safeguard sessions list
safeguard checkpoints list --session SESSION_ID
safeguard checkpoints restore CHECKPOINT_ID --session SESSION_ID --dry-run
safeguard checkpoints restore CHECKPOINT_ID --session SESSION_ID --files-only
--dry-run prints what would change, as a diff per file. --files-only restores the files and keeps the transcript. A restore is itself kept as a checkpoint, so you can undo the undo. One limit to remember: anything a shell command writes is not snapshotted. That is why step 1 says commit or start clean.
6. Use it for ordinary machine tasks too. The same assistant can find and read files, edit code and run commands, with your approval. The docs give "what's the latest file in ~/Downloads" as an example. A few more in the same spirit:
find every Dockerfile under this folder and list the base images
read .github/workflows/ci.yml and tell me which Node version it uses
rename the env var PAYMENTS_TIMEOUT to PAYMENTS_TIMEOUT_MS across this folder
The last one edits files, so it asks first unless you are in Accept edits.
Afternoon: keep going from the desktop and your phone
A CLI session is live. It shows in the web app, the desktop app and the phone app, and other devices can send work to it. That changes what "away from the terminal" means.
On the desktop app. The desktop app (3.2.2 on the download page) runs on Windows 10 and 11, macOS 12 and later, and Linux as an AppImage, which needs the CLI on your PATH. Your CLI session appears in its conversation list. From there you can send work to a computer running the CLI: pick the computer and the folder, then approve each command and file edit. The desktop app guide covers install and first run.
On your phone. The Android app is on Google Play, with a direct APK for phones without Google Play, and the iOS app is on the App Store for iPhone and iPad. The same conversations are there. Say you are in a meeting and want the tests run on the branch you left open:
- Open the conversation on the phone, or start a new one.
- Tap "Work on my computer", then pick the computer running the CLI and the folder.
- Ask: "run npm test in this folder and tell me what failed".
- The command waits on the phone. Choose Allow once, Allow for turn, or Deny.
- Read the answer when it lands.
The recorded Android session below shows that flow. The same conversations appear on the phone; "Work on my computer" picks a computer running the CLI and a folder; the command waits for Allow once, Allow for turn or Deny on the phone; and the answer shows the tests passed.
Click through it at your own pace, or open it full screen.
Allow once is the careful choice: it approves that one command. Allow for turn approves the rest of that turn, which is fine for a short, known sequence such as install then test. For Android specifics, see Safeguard on Android phones and tablets.
Moving small things between devices. Two commands help:
safeguard devices
safeguard send --to pixel --link https://github.com/acme/payments-api/pull/42
safeguard send --to pixel --text "check the lockfile diff before merging"
devices lists your signed in devices that can send and receive. send takes a device name, a unique prefix of the name, or an id, and sends a link or up to 8,000 characters of text.
Before you push: review, rescan, and hand off to CI
The last ten minutes of the day decide whether tomorrow starts clean.
1. Review the working tree.
safeguard review
safeguard review --base main
review reviews the working tree changes for correctness and security. --base diffs against a Git ref instead, which is the right view for a whole branch. For more on this step, see reviewing AI generated code before merge.
2. Read the diff yourself as well.
git diff --stat
git diff
Check that every changed file has a reason you can name. A dependency fix that also touched source files deserves a second look.
3. Scan again. Type /scan . in the session, or run safeguard scan --dir .. A finding is fixed when the scanner stops reporting it, not when the assistant says so.
4. Commit and push. Use the suggested commit message as a starting point, then edit it so it names the packages and versions that moved.
5. Let CI repeat the check. In a pipeline nobody is there to approve anything, so use the non-interactive commands. safeguard ci scan scans the commit as a new version of its Safeguard project. With --local the scan runs on the CI runner and only results are uploaded, never the source. It authenticates with a secret key from Settings, Secret Keys, that has the scans:trigger scope (and scans:read for --wait), stored as the CI secret SAFEGUARD_API_KEY.
A GitHub Actions job might look like this. It assumes the CLI is installed on the runner with the same install command as above.
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: 'npm'
- run: npm ci
- run: npm test
- name: Safeguard scan
env:
SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
run: safeguard ci scan --local --wait --fail-on high
npm ci installs exactly what the lockfile says and exits with an error if package.json and the lockfile disagree, so the scan sees what will ship. --fail-on high fails the step when the scan has a vulnerability at high or above. If your team uses gates, --fail-on-gate Release waits for that gate's policies and fails the step when the gate fails. Policies and gates are evaluated in the platform, not by the CLI.
For a written summary on each build, add one assistant turn:
safeguard exec "summarise the critical findings in this repository"
exec runs in Strict mode by default: nothing is asked, and anything the policy file has not pre-approved is denied. It refuses to run outside a Git repository, because there would be no way to undo what it changes. The full pattern is in Safeguard CLI in CI with safeguard exec.
Troubleshooting
safeguard: command not found after install. Open a new terminal so your shell reloads PATH. If it still fails, check where the installer put the binary and add that folder to PATH.
/login opens the browser but the terminal does not continue. Make sure you approved the session in the browser tab that opened, then check /whoami. If you are on a remote machine over SSH, run safeguard doctor and read the sign-in line.
The scan is slow the first time. Scanners download on first use, so the first /scan . on a new machine takes longer than later ones.
The phone does not list your computer. The computer has to be running the CLI and signed in to the same account. If you want it reachable whenever it is on, run safeguard runner install. Then check safeguard devices from the computer.
safeguard exec refuses to start. It needs a Git repository. Run it from the repository root. --skip-git-repo-check exists, but you lose the easy undo that Git gives you.
A command was denied in CI. exec defaults to Strict, so any action the policy has not pre-approved is denied. Add the specific allow rule (for example --allowedTools 'Bash(npm test:*)') rather than switching to --yolo.
Restore did not bring back a file. Checkpoints cover files the assistant wrote or edited. Files a shell command wrote are not snapshotted, so use Git for those.
Common mistakes
Starting in the wrong folder. The session, @ attachments and /resume are all tied to the folder you started in. Always cd to the repository root first.
Leaving the mode on whatever it was. Accept edits from yesterday's refactor is the wrong mode for today's unfamiliar repository. Glance at the bar under the input, where the current mode is shown, before you ask for changes.
Using --yolo on your real checkout. It approves everything, including installs that run package scripts. It belongs in throwaway sandboxes only.
Asking for a fix before scanning. Without fresh scan data the assistant has less to go on. Scan first; it takes one command.
Trusting the summary instead of the rescan. The rescan is the proof. Run it every time.
Skipping git status before a session. If the tree is dirty, you cannot tell your changes from the assistant's, and shell writes are not in the checkpoints.
Treating the CLI as the policy engine. The CLI scans and fixes. Pass or fail rules live in the platform's policies and gates, so set them up there and let CI call them.
FAQ
Can I use my Claude, ChatGPT or Codex plan with the Safeguard CLI?
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 the CLI docs or /model for connecting a model. You can also connect Claude or ChatGPT to the Safeguard MCP server and use Safeguard from the chat you already use.
Does my source code leave my machine?
When the local runner runs platform scan jobs, your source code stays on your machine; only SBOMs and findings are uploaded. safeguard findings goes further and uploads nothing at all.
Will the assistant change files without asking?
Only in the ways the mode you chose allows. In Ask, every edit and command asks first. In Auto, the default, read-only commands and what the policy allows run, and anything else asks. Plan changes nothing. Only --yolo approves everything, and you have to choose it.
What is the difference between /resume and checkpoints?
/resume picks up your last conversation in that folder, so you can carry on where you stopped. Checkpoints are snapshots of files before each assistant edit, which /rewind and safeguard checkpoints restore use to put files back.
Can I approve work from my phone?
Yes. From the phone app, "Work on my computer" sends work to a computer running the CLI. Each command waits for Allow once, Allow for turn or Deny on the phone.
Is it only for security work?
No. The assistant has tools for your local files and your Safeguard data, so you can find and read files, edit code and run commands with your approval, as well as scan and fix findings.
Which mode should I use in CI?
Strict, which is what safeguard exec uses by default. Pre-approve the exact commands the job needs and let everything else be denied.
Try it yourself
This walkthrough sets up the runner on your own machine: pick the platform, start it, approve it with its device code, then use the same CLI to scan from the terminal.
Click through it at your own pace, or open it full screen.
The CLI is one surface of one platform. The download page also lists the desktop app for Windows, macOS and Linux, iOS and Android apps, IDE extensions for VS Code, JetBrains and Open VSX editors, a browser extension, and cloud options with nothing to install, including a cloud sandbox tenant against a seeded demo repo that is free for seven days with no card. Start in the terminal, carry on at the desktop, approve from your phone.
Ready? Download the Safeguard CLI, run safeguard, type /login, then /scan .. The full reference is in the CLI docs.
Quick check
Which permission mode changes nothing on disk while you plan?
Plan. It reads and plans only, so you can work out the order of a large change before any file is touched.
What does safeguard findings do differently from a normal scan?
It runs one scanner locally and prints the findings, and nothing is uploaded. No project is registered, even when the CLI is signed in.
Why commit or start from a clean tree before a session?
Checkpoints cover files the assistant writes or edits, but not files a shell command writes. A clean Git tree lets you see and undo everything.
Sources
- Safeguard CLI overview
- Safeguard CLI interactive terminal
- Safeguard downloads
- GitHub Docs: using secrets in GitHub Actions
- actions/setup-node README
- npm ci documentation
Last reviewed: 21 October 2026.
