Safeguard CLI Tips for Power Users: Flags, Sessions, Undo and CI

Power users get more from the Safeguard CLI by setting it up once, starting each session in the right folder with the right approval mode, keeping undo cheap with checkpoints and git, scanning locally before anything is uploaded, scripting with safeguard exec, and handing work between terminal, desktop and phone. Every tip uses real flags from the CLI's help.

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 use Safeguard from the chat you already use.

What you will have at the end

• A CLI that updates on your terms, stores its token in your OS keychain and reads your settings in a predictable order.
• Your existing Claude Code or Codex setup carried over, so you do not rebuild it.
• Shell habits for opening, naming, continuing and forking sessions.
• An approval mode and tool rules matched to each kind of task.
• A tested way to undo the assistant's edits, and a clear idea of what undo does not cover.
• A local scan, review and fix loop, plus a pipeline step that fails on a platform gate.
• A machine your phone and desktop can send work to, with every command still approved by you.

The examples use a sample Node.js service called payments-api. Flags were read from safeguard --help and each command's --help on CLI v11.11.0. Run safeguard COMMAND --help on your own build before scripting anything, since help is the authority when it and the docs differ.

1. Set up once, then stop thinking about it

1. Check before you update. safeguard self-update --check reports whether a newer release exists and installs nothing. safeguard self-update installs it: it verifies a signed release manifest, checks the archive digest, runs the new binary to prove it works, and keeps the old one as safeguard.previous. It refuses to cross a major version unless you pass --allow-major. Not to be confused with safeguard update, which refreshes vulnerability databases.
2. Run the doctor after any change. safeguard doctor checks environment, sign in, tools and policy and changes nothing. It exits 0 whenever the checks ran, so read the lines, not the exit code. -v adds the sandbox capability grants.
3. Move the token into your keychain. By default the sign in token lives in ~/.scanner/token.json with mode 0600. Set SAFEGUARD_CREDENTIAL_STORE=native to use macOS Keychain, Linux Secret Service or Windows DPAPI instead, or auto to use the native store where it exists.
4. Know the settings order. From highest to lowest: command line flags, .safeguard/settings.local.json in the workspace, .safeguard/settings.json in the workspace, ~/.safeguard/settings.json, built-in defaults. Keep personal overrides in settings.local.json and out of git. The shared settings.json applies only after you run safeguard trust in that workspace, so a cloned repository cannot change your setup on its own.
5. Bring your existing agent setup. safeguard import claude or safeguard import codex converts a Claude Code or Codex setup into Safeguard configuration; --force overwrites existing Safeguard files. Separately, safeguard other-agents is on by default: Claude Code's, Codex's and OpenCode's agents, skills, custom commands, MCP servers, hooks, permissions and instructions are read below Safeguard's own. safeguard other-agents off reads only Safeguard's files.
6. Add the MCP servers you use. safeguard mcp add docs --url https://mcp.example.com/mcp --oauth adds an HTTP server and signs in through your browser. New servers default to --approval-mode ask. safeguard mcp list shows what is configured, safeguard mcp disable docs switches one off without deleting it, and --user stores it in ~/.safeguard instead of the workspace.

2. Start each session in the right place

Most surprises come from a session that started in the wrong folder or with the wrong context. These flags fix that before the first prompt.

# Open the terminal in a project without cd-ing there first, and name the session
safeguard -C ~/code/payments-api -n lodash-upgrade

# Continue the most recent session in this workspace
safeguard -c

# Resume a specific session, or copy it into a new one instead of extending it
safeguard --resume=SESSION_ID
safeguard --resume=SESSION_ID --fork-session

# Let the assistant read a sibling folder too, and attach a screenshot
safeguard --add-dir ../shared-lib -i ./error.png

Inside the terminal, /resume picks up the last session in the current folder, @ opens a file picker for the folder you started in, and /model shows or switches the model. On the command line, -m picks the model tier and --effort low, medium or high sets reasoning effort for the run.

For parallel experiments, safeguard sessions fork SESSION_ID --worktree copies a session into a new one with its own git worktree, so two approaches never touch the same files. safeguard sessions list shows saved sessions, newest first.

3. Match the approval mode to the task

The assistant can read files, edit code and run commands on your machine, with your approval. /permissions in the interactive terminal offers five modes:

On the command line, -a (or --permission-mode) takes supervised, edits, plan, guarded, strict or autonomous. The --yolo flag approves everything; keep it for throwaway sandboxes only.

Modes are coarse. Rules are precise, and power users lean on them:

• --allowedTools 'Bash(go test:*)' pre-approves one family of commands, in policy.yaml syntax. Repeat the flag for more.
• --disallowedTools 'Read(~/.ssh/**)' denies reads of a path, whatever the mode.
• --restricted gives a read-only tool set: no writes, no shell, no network. Useful for "explain this codebase" sessions.
• --sandbox confines every write to the workspace at the kernel level using Landlock on Linux, and refuses to start where that is unavailable.
• --safe-mode ignores every local customisation (settings, hooks, skills, plugins, SAFEGUARD.md). When the CLI behaves oddly, this tells you whether your config is the cause.

The recorded session below shows Ask style approvals end to end. It was captured on a Mac on 21 October 2026 against the sample payments-api project with test data. The CLI is installed with the curl command (checksum verified), checked with safeguard --version and opened with safeguard. Asked to "fix the lodash CVE in this repo", the assistant reads the finding, files and advisory, then asks before each command, and you press y or n. It edits package.json to lodash 4.17.21, runs npm install and npm test with approval, prints a summary with a suggested commit message and pushes nothing. Then it shows /permissions, /model and /scan ..

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

4. Make undo cheap

The CLI snapshots every file the assistant writes or edits before it changes it. Those checkpoints are what /rewind uses inside the terminal, and you can drive them from the shell:

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 a diff per file and changes nothing. A restore puts every changed file back, removes files the assistant created and, without --files-only, rolls the transcript back to the same point as /rewind does. The state it overwrites becomes a new checkpoint, so a restore can itself be undone. A checkpoint can be named by a unique prefix of its ID.

The gap to remember: anything a shell command writes is not snapshotted. npm install, a code generator or a build step can change files that no checkpoint covers. So:

1. Start on a branch: git switch -c fix/lodash.
2. Commit or stash before a session that will run commands. git stash saves local changes and resets the working tree to HEAD; git stash pop puts them back.
3. Approve commands that write only when you know what they write.
4. Use /rewind for the assistant's edits and git for everything else.

safeguard exec builds this in: it refuses to run outside a git repository, because there would be no way to undo what it changes, unless you pass --skip-git-repo-check.

5. Keyboard and context habits

alt+enter also inserts a newline where the terminal passes it through, but Windows consoles intercept it. shift+enter is not built in; you can bind it to send a newline in Windows Terminal's settings.

6. Scan, review and fix in a tight loop

The quickest feedback loop is local. safeguard findings runs one scanner on your machine and prints a normalised list of findings. Nothing is uploaded and no project is registered, even when you are signed in.

# Dependencies in this folder, as JSON lines
safeguard findings sca --dir . --json

# A container image you are about to push
safeguard findings container --image payments-api:dev

# Infrastructure as code in ./infra
safeguard findings iac --dir ./infra

When you want results on the platform, scan for real. Each run takes one target and writes JSON such as vuln.json, license.json and collection.json under the output folder:

safeguard scan --dir . --output ~/safeguard-results
safeguard container-scan --image payments-api:dev
safeguard iac-scan --target ./infra

safeguard scan exits 0 when the scan ran, whatever it found, 1 when the command failed, and 2 when results were written but the vulnerability scan did not run. There is no severity threshold flag on scan; gating happens through platform policy gates. For monorepos, scan packages one at a time with --dir ./packages/app1, which also avoids memory trouble on large trees.

Then fix and review:

# Preview dependency fixes for critical findings, patch versions only
safeguard fix --dry-run --severity critical --patch-only

# Limit it to one package
safeguard fix --dry-run --package lodash

# Review the branch against main for correctness and security
safeguard review --base main

For SBOM work, safeguard sbom --dir ./service --output service-sbom.json writes an SPDX JSON SBOM and stops there, and safeguard validate service-sbom.json --strict checks it, treating warnings as errors. validate also handles CycloneDX and VEX documents, and --recursive walks a folder of them.

7. Script it

safeguard exec runs one assistant turn without prompting and prints the result. Its default permission mode is strict: nothing is asked, and anything the policy file does not pre-approve is denied.

# One turn, machine readable
safeguard exec "summarise the critical findings in this repository" --output-format json

# Read the prompt from stdin
cat prompts/weekly-review.txt | safeguard exec -

# Force the answer into a shape your script can parse
safeguard exec "list outdated direct dependencies" --output-schema schema.json

# Allow exactly the commands the task needs
safeguard exec "run the tests and explain any failure" --allowedTools 'Bash(npm test:*)'

Long jobs can run detached with --background; follow them with safeguard sessions attach SESSION_ID or read output later with safeguard sessions logs SESSION_ID. For slash commands in a script, safeguard runner slash /status --json runs them through the terminal's own dispatcher and prints one JSON object per command.

In a pipeline, safeguard ci scan is the step that ties a commit to its Safeguard project. With --local it scans the checkout on the CI runner and uploads only the results, never the source. With --wait --fail-on high it fails the step on a high or critical vulnerability. With --fail-on-gate Release it waits for that gate's policies to be evaluated in the platform and fails the step when the gate fails. It authenticates with a secret key that has the scans:trigger scope (plus scans:read for --wait), stored as the CI secret SAFEGUARD_API_KEY. A GitHub Actions step looks like this:

- uses: actions/checkout@v7
- name: Install Safeguard CLI
  run: curl -fsSL https://cli.safeguard.sh/install | SAFEGUARD_VERSION=11.11.0 bash
- name: Safeguard scan
  env:
    SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
  run: safeguard ci scan --local --wait --fail-on high

Pin SAFEGUARD_VERSION so builds do not change under you. In a fresh container the scanners may be missing; put syft and grype on PATH or set TOOLS_DIR. The CI guide for safeguard exec goes further.

8. Work across devices

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. A few commands make that useful day to day.

1. safeguard devices lists your signed-in devices that can send and receive.
2. safeguard send --to pixel --link https://app.safeguard.sh sends a link to the device named pixel. --text sends up to 8,000 characters, and --stdin sends whatever you pipe in, such as a scan summary.
3. safeguard inbox shows what your other devices sent to this CLI. safeguard inbox open ITEM_ID --copy copies a text item to your clipboard.
4. safeguard runner install registers the runner as a per-user login service (a systemd user unit, a LaunchAgent or a logon scheduled task), so your phone or browser can send work to this machine from any network while it is on. Nothing listens on a port; the runner only opens outbound HTTPS. --workspace sets its folder and -a its permission mode. safeguard runner uninstall removes it.

From the desktop or phone app you then pick the computer and the folder and approve each command and file edit. This recorded desktop session, captured on 21 October 2026 with the sample project, shows the flow. The CLI session appears in the desktop app's conversation list. "2 connected" shows the computer, the browser and Safeguard cloud. You ask for work on your computer, it asks which computer and folder, you pick the folder, then Approve or Deny each command and file edit. It ends with the upgrade done and tests passing.

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

The desktop app guide covers installing it on Windows, macOS and Linux.

Do the work properly with the Safeguard CLI

All of these tips serve one idea. 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 fix what it finds. It writes code too. The assistant has tools for your local files and for your Safeguard data, so one session can answer "what's the latest file in ~/Downloads", count your critical vulnerabilities, and fix a CVE with your approval.

Used that way, you write and fix code with an assistant that already knows your vulnerabilities. You scan what any agent changed before you merge, whether the change came from you, from Safeguard or from another coding tool; the guide to reviewing AI generated code before merge shows that step. And your source stays on your machine: when the local runner runs platform scan jobs, only SBOMs and findings are uploaded.

It is one platform on every surface. The CLI is a single static binary for macOS, Linux and Windows, for the terminal and CI/CD. The desktop app runs on Windows, macOS and Linux, the mobile apps on iOS and Android, and there are IDE and browser extensions plus cloud options with nothing to install. Policies and gates are evaluated in the platform, not by the CLI.

Troubleshooting

A flag in this post is rejected. Your build may be older. Run safeguard --version, then safeguard self-update --check.

Two versions fight over your PATH. which -a safeguard (or Get-Command safeguard -All) lists every copy; the first one wins. An old build in ~/go/bin is a common cause.

safeguard exec refuses to start. It needs a git repository. Run it inside one, or pass --skip-git-repo-check only when you accept there is no undo.

--sandbox will not start. It needs Landlock on Linux and refuses to run where that is unavailable. Use --restricted or a stricter approval mode instead.

Shared repository settings are ignored. Run safeguard trust in the workspace. Until then only your user and local settings apply.

A CI scan finds nothing. Install dependencies first so lock files exist, and make sure syft and grype are on PATH or in TOOLS_DIR.

Something behaves strangely after you changed config. Start once with --safe-mode. If the problem disappears, a local setting, hook, skill or plugin is the cause. Then run safeguard doctor and check ~/.sg/logs/safeguard.log.

Common mistakes

Trusting /rewind with shell output. It covers the assistant's file edits, not what npm install or a build wrote. Commit first.

Using --yolo because Ask felt slow. Use Accept edits or targeted --allowedTools rules instead. Keep --yolo for throwaway sandboxes.

Reading the doctor's exit code. It is 0 whenever the checks ran. Read the output.

Confusing update and self-update. The first refreshes vulnerability databases; the second replaces the binary.

Putting personal overrides in settings.json. That file is shared with the repository. Personal settings belong in settings.local.json.

Scanning a whole monorepo in one go. Scan packages separately with --dir.

Leaving a CI build unpinned. Pin SAFEGUARD_VERSION so a new release cannot change flags or output mid-sprint.

FAQ

Can I use my Claude or ChatGPT subscription 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 ChatGPT or Claude to the Safeguard MCP server, as in the guide to connecting ChatGPT to Safeguard.

Will my Claude Code or Codex configuration carry over?

safeguard import claude or safeguard import codex converts it into Safeguard configuration. With other-agents on, which is the default, Claude Code, Codex and OpenCode configuration is also read below Safeguard's own.

What is the difference between findings and scan?

safeguard findings runs one scanner locally and prints results; nothing is uploaded. safeguard scan builds an SBOM, matches it against vulnerability databases and writes JSON under the output folder.

Does /rewind undo commands the assistant ran?

No. It restores files the assistant wrote or edited and removes files it created. Output from shell commands is not snapshotted, so use git for that.

Can the CLI fail my pipeline on a policy gate?

Yes, through safeguard ci scan --wait --fail-on-gate with the gate's name. The gate is evaluated in the platform; the step reads the result.

Does a runner I install open a port on my machine?

No. safeguard runner install sets up a login service that only opens outbound HTTPS. Nothing connects to it.

Which approval mode should I use day to day?

Auto, the default, suits most work. Use Plan for proposals, Ask for unfamiliar repositories, Accept edits for trusted refactors and Strict in CI.

Try it yourself

This demo walks through setting 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.

Download the CLI from safeguard.sh/download, keep the CLI docs open, and pick two tips from this list to try this week.

Quick check

Sources

• Safeguard CLI docs
• Safeguard CLI: interactive terminal
• Safeguard CLI: usage
• Safeguard CLI: installation
• Safeguard CLI: configuration
• Safeguard CLI: troubleshooting
• Safeguard download page
• Git docs: git stash
• actions/checkout on GitHub
• GitHub Docs: using secrets in GitHub Actions

Last reviewed: 21 October 2026.