Use the Safeguard CLI as a General Terminal Assistant

The Safeguard CLI is not only a scanner. Run safeguard with no arguments and you get an assistant in your terminal that can find and read files, edit code and run commands with your approval, and answer questions about your Safeguard data. You ask in plain words, and anything that changes your machine waits for a yes.

This guide shows how to make it part of your normal terminal day: the chores, the code changes, the one-off questions, and the security checks that now sit in the same place.

What you will have at the end:

• The CLI installed, signed in and opened in a project.
• Six worked walkthroughs for everyday tasks: finding files, reading and summarising, editing code, running commands, scripting one-off turns and picking up where you left off.
• A permission setup that keeps routine work quick and risky work supervised.
• The habit of finishing a change with a scan and a review, without leaving the terminal.

You can keep the AI plan you already have. 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 would rather stay in a chat window, you can also connect Claude or ChatGPT to the Safeguard MCP server, as our guide to connecting Claude to the Safeguard MCP server explains.

What the assistant can and cannot do

Be clear about the boundaries before you rely on it. According to the interactive terminal docs, the assistant has tools for your local files and for your Safeguard data, and it picks whichever a question needs. The examples in the docs show the range:

• "what's the latest file in ~/Downloads" uses the file tools.
• "fix the lodash CVE in this repo" uses both: it reads your Safeguard findings and edits your code.
• "how many critical vulns do we have" uses your Safeguard data.

So in practice it can:

What it is not: a way to act on your machine without you. Tools that change things, such as writing a file, editing code or running a command, ask before they act according to your /permissions mode. Treat it as a capable pair of hands that checks with you, not as something that runs off on its own.

Set it up in five minutes

1. Install. On macOS and Linux:

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

   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, for macOS, Linux and Windows on x86_64 or arm64 (Windows on x86_64 only). Platform-specific steps, including Windows, are in our install guides; the Linux install guide is a good place to start.

2. Check it runs. safeguard --version prints the version.

3. Open a project. Change into a folder you work in every day, then run safeguard. The folder you start in matters: @ attaches files from it, and /resume picks up sessions per folder.

4. Sign in. Type /login. Your browser opens to approve the session.

5. Pick a model. Type /model to see the current model or switch. To connect the Claude, ChatGPT or Codex plan you already have, see /model and the CLI docs.

6. Check the approval mode. Type /permissions. The default is Auto: read-only commands and what the policy allows run, and anything else asks. Leave it there for now.

7. Learn the keys you will use daily. From the docs: ctrl+j inserts a newline (the one that works everywhere), esc interrupts whatever is running without exiting, PgUp and PgDn scroll the transcript, and typing / opens a filtered command palette.

If anything misbehaves, run safeguard doctor. It checks everything the agent depends on, changes nothing, and prints what is wrong in the order that matters.

Everyday walkthroughs

Each walkthrough is something you might otherwise do with a handful of shell commands and a search engine. Here you describe the outcome and approve the steps.

1. Find the file you need

You know a file exists but not where, or you want the newest thing in a folder.

1. Ask: "what's the latest file in ~/Downloads".
2. Narrow it: "find the YAML files under deploy that mention payments-api".
3. Follow up: "which of those were changed in the last week".

These are reads, so they run in every mode except Strict without a prompt. If you want the assistant to look in a folder outside the one you started in for the whole session, start it with --add-dir:

safeguard --add-dir ../shared-config

2. Read, summarise and explain

Reading is where a terminal assistant saves the most time, because you skip opening ten files to answer one question.

1. Type @ and pick a file. The docs describe @ as opening a file picker for the folder you started in; the chosen file is attached so the assistant can read it.
2. Ask about it: "@logs/app.log group these errors by cause and tell me which one started first".
3. Ask about code: "@src/payments/refund.ts explain the retry logic and where it could double-charge".
4. Use /copy to copy the last answer to your clipboard for a ticket or a chat message.

If the conversation gets long, /compact summarises it to free context, and /clear starts fresh and forgets what the assistant was carrying.

3. Edit code

This is where approvals start to matter.

1. Make sure your tree is clean so the assistant's changes stand alone. git status --short shows what is modified or untracked.

2. Ask for the change in specific terms: "add a check in createRefund that rejects amounts above the original charge, and add a unit test for it".

3. The assistant reads the relevant files, then proposes edits. In Auto or Ask mode, each edit waits for you.

4. When it is done, review the result yourself:

   git diff
   

5. For a large, mechanical change such as a rename across many files, switch to Accept edits with /permissions. File edits in the folder and read-only commands then run without a prompt, other commands still ask, and you review everything once with git diff.

The CLI writes code, not only scans it. Use it for features and refactors the same way you would use it for fixes.

4. Run commands

You can ask for commands by describing what you want rather than recalling flags.

1. Ask: "what npm scripts does this project have". (npm run with no script name lists them, per the npm docs, and the assistant can run that or read package.json.)
2. Ask: "run the tests and tell me which ones fail and why".
3. When the command comes up for approval, read it before you answer. In the terminal you press y or n.
4. Ask for the next step: "fix the first failing test, then run only that test file again".

npm test runs whatever the test script in package.json defines, so the assistant is running exactly what you would. If you approve the same routine command many times a day, add an allow rule when you start the session instead of switching to a looser mode:

safeguard --allowedTools 'Bash(npm test:*)'

The flag takes rules in policy.yaml syntax, and --disallowedTools does the reverse. A deny rule such as --disallowedTools 'Read(~/.ssh/**)' keeps key folders out of reach in any mode.

The recorded session below puts reading, editing and running together. On a sample project called payments-api, it 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.

5. One-off questions from scripts and aliases

Not everything needs an interactive session. safeguard exec runs one assistant turn, prints the result and exits.

# A read-only question, answered and done
safeguard exec -a plan "list the TODO comments in src and group them by file"

# Run it against another folder without changing directory
safeguard exec -C ~/code/payments-api -a plan "which direct dependencies have known vulnerabilities"

# Machine-readable output for another script
safeguard exec -a plan --output-format json "summarise the critical findings in this repository"

Three details from safeguard exec --help to know:

• The default permission mode is Strict: nothing is asked and anything not pre-approved is denied. That is why the examples pass -a plan for read-only questions.
• 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; use it only for read-only work.
• Pass - instead of a prompt to read the prompt from standard input.

The same command runs in CI. Our guide to safeguard exec in CI covers the pipeline setup.

6. Pick up where you left off

Real work spans days and devices.

1. Same folder, later. Open safeguard in the same folder and type /resume to pick up your last session there. From the shell, safeguard -c continues the most recent session in the workspace.
2. Name sessions you will come back to. safeguard -n refund-limits names the session so it is easy to find.
3. From another device. 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 the computer running the CLI.
4. Send yourself something. safeguard devices lists your signed-in devices, safeguard send --to <device> --text "..." sends text or a link to one of them, and safeguard inbox shows what your other devices sent to this CLI.

Sending work from the desktop app looks like this. The CLI session shows in the desktop app's conversation list, and "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 you Approve or Deny each command and file edit. The recording ends with the upgrade done and the tests passing.

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

Fold security into the same session

The difference between a general terminal assistant and the Safeguard CLI is that the security work is already there. You do not switch tools to check what you just changed.

Scan the folder. In the session, /scan . scans the current folder. From the shell:

safeguard scan --dir .

That builds an SBOM and matches it against vulnerability databases. Results land as JSON files under ./output, including vuln.json and license.json. The same command takes --repo, --image or --sbom for a repository URL, a container image or an existing SBOM.

Check without uploading anything. safeguard findings sca --dir . runs a scanner on this machine and prints a normalized list of findings. Its help says nothing leaves the machine: no project is registered and nothing is uploaded, even when you are signed in.

Review before you commit. safeguard review reviews the working-tree changes for correctness and security. Add --base main to diff against a branch instead. This is useful for any change, including ones made by another coding agent; our post on checking coding agent changes with the Safeguard CLI goes deeper.

Generate and check SBOMs. safeguard sbom writes an SPDX-JSON SBOM for a folder or an image. safeguard validate checks CycloneDX, SPDX and VEX documents.

Ask about the whole estate. "how many critical vulns do we have" answers from your Safeguard data, not just the folder you are in.

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.

Choose a permission mode for general work

/permissions offers five modes. Here is how each fits general terminal work:

There is also a --yolo flag that approves everything. Keep it for throwaway sandboxes only.

Two facts make the choice easier. First, files the assistant writes or edits are snapshotted before each change, and safeguard checkpoints (the same checkpoints /rewind uses) can list, preview with --dry-run and restore them. Second, anything a shell command writes is not snapshotted. Edits are easy to undo; commands are not. That is why commands deserve your attention even when edits do not.

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. Using it as your everyday terminal assistant means the same tool that renames a function also knows whether the package you just added has a known vulnerability.

A simple daily loop:

1. Open safeguard in the project and /resume if you were here yesterday.
2. Ask questions and make changes in plain words, approving edits and commands as they come up.
3. Before committing, run /scan . and safeguard review.
4. Commit with the suggested message or your own.
5. Leave the session open; check on it or send it work from the desktop or phone app.

Everything you need is on the download page: the CLI, the desktop app for Windows, macOS and Linux, and the mobile apps for iOS and Android. For a broader tour of the assistant, see the Safeguard CLI as an AI assistant on your machine.

Troubleshooting

"Not signed in" or questions about your data fail. Type /login and approve in the browser. /whoami shows who you are signed in as.

@ does not show the file I want. The picker lists the folder you started in. Restart from the right folder, use -C path, or add the other folder with --add-dir.

A command keeps asking even though I approved it before. Auto only runs read-only commands and what the policy allows. Add a narrow allow rule such as --allowedTools 'Bash(npm test:*)'.

safeguard exec refuses to run. It needs a git repository. Run it inside one, or add --skip-git-repo-check for read-only questions.

safeguard exec does nothing useful. Strict is its default and denies anything not pre-approved. Use -a plan for read-only questions.

I cannot type a multi-line prompt. Use ctrl+j for a newline. On Windows consoles alt+enter is intercepted, so ctrl+j is the reliable choice.

The assistant is doing something I did not expect. Press esc to interrupt, then deny the next step or change the mode.

Something else. Run safeguard doctor and read the lines it prints, not just the exit code.

Common mistakes

• Starting in your home folder. @ and /resume work per folder, and Accept edits applies to the folder you started in. Start where the work is.
• Approving commands without reading them. The prompt is only useful if you read it. Deny anything you do not understand and ask why it is needed.
• Mixing your changes with the assistant's. Commit or stash first so git diff shows only its work.
• Assuming a revert covers everything. Checkpoints cover file edits, not files written by shell commands.
• Skipping the scan after a dependency change. A one line manifest change can pull in many transitive packages. Run /scan . before you commit.
• Using --yolo on your laptop. It approves everything, including commands you cannot undo.

FAQ

Can the Safeguard CLI do things that have nothing to do with security?

Yes. It has tools for your local files, so it can find and read files, edit code, write new files and run commands with your approval. The docs' own example is "what's the latest file in ~/Downloads".

Does it act without asking?

Not by default. Tools that change things ask before they act, according to your /permissions mode. Auto, the default, runs reads, read-only commands and what the policy allows, and asks for anything else.

Can I use my existing Claude, ChatGPT or Codex subscription?

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.

Does my source code leave my machine?

When the local runner runs platform scan jobs, only SBOMs and findings are uploaded, never source. safeguard findings uploads nothing at all.

Can I use it in scripts?

Yes. safeguard exec "your question" runs one turn and exits. Use -a plan for read-only questions and --output-format json when another program reads the result.

How do I undo a change the assistant made?

For file edits, use /rewind or safeguard checkpoints restore with --dry-run first to preview. For anything a command wrote, use git or your backup.

Can I start a task on my laptop and approve it from my phone?

Yes. A CLI session shows in the web, desktop and phone apps, and you can send work to a computer running the CLI and approve each command and file edit from there.

Does it read my Claude Code or Codex settings?

safeguard other-agents is on by default and reads Claude Code's, Codex's and OpenCode's agents, skills, custom commands, MCP servers, hooks, permissions and instructions below Safeguard's own. safeguard import claude or safeguard import codex converts a setup into Safeguard configuration.

Try it yourself

This demo shows 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.

Quick check

Sources

• Safeguard CLI docs
• Safeguard CLI interactive terminal docs
• Safeguard CLI slash commands docs
• Safeguard download page
• npm run, npm docs
• npm test, npm docs
• git status, Git documentation
• git diff, Git documentation

Last reviewed: 21 October 2026.