Find and Read Files on Your Machine with the Safeguard CLI

To find and read files with the Safeguard CLI, open a terminal in the folder you care about, run safeguard, and ask in plain English, for example "what's the latest file in ~/Downloads". The assistant searches and reads local files for you, attaches a file when you type @, and asks before edits and commands as your /permissions mode sets.

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 the chat you already use, you can also connect Claude or ChatGPT to the Safeguard MCP server and ask about your Safeguard data from there.

This guide is about the everyday part of the CLI that people tend to skip past: using it to look things up. Not every task is a fix. Most days you need to know where a setting lives, what a log says, which file pulls in a package or what changed in a config. The same assistant that fixes vulnerabilities is a good way to answer those questions, because it can read your files and your Safeguard findings in one conversation.

What you will have at the end

Work through this guide once and you will have:

• The Safeguard CLI installed, signed in and started in the right folder, with a permission mode you chose on purpose.
• A set of prompts that find files by name, content, age or size, and get you the answer instead of a list of paths.
• A habit for reading files with @, so the assistant works from the exact file you mean.
• A way to cross-reference files with your scan results, so "which file declares this vulnerable package?" takes one question.
• A read-only setup for days when you want answers and no changes at all.
• The same file questions available from the desktop app and your phone, sent to the computer running the CLI.

Everything below uses commands from the Safeguard CLI docs and the CLI's own --help output. If the two ever disagree, the docs say the --help output is correct.

Set up: install, sign in and start in the right folder

The folder you start in matters more for file work than anything else. The @ file picker lists files from the starting folder, /resume picks up the last session in that folder, and the assistant reads from it by default. Start where the files are.

1. Install the CLI. On macOS or Linux, run the install script. On Windows, use PowerShell. It is one static binary with no Node, Python or JVM to install. The download page notes that the installer verifies a published SHA256SUMS file before it changes your PATH. If you want a guided version, see installing the Safeguard CLI on macOS.

# macOS and Linux
curl -fsSL https://cli.safeguard.sh/install | bash

# Windows (PowerShell)
irm https://cli.safeguard.sh/install.ps1 | iex

2. Check the install. Run safeguard --version. If your shell cannot find the command, open a new terminal so the PATH change takes effect.

3. Go to the folder and start the terminal. Running safeguard with no arguments opens the interactive terminal.

cd ~/code/payments-api
safeguard

4. Sign in. Type /login. Your browser opens, you approve the session and the terminal picks it up. You need this for questions about your Safeguard data, such as findings and projects. On a machine without a browser, exit and run safeguard login --no-browser, then open the printed URL on any device and enter the code.

5. Check health. Type /doctor to confirm health and connectivity. From a normal shell, safeguard doctor checks the environment, sign-in, tools and policy and changes nothing.

6. Choose your approval mode. Type /permissions. The current mode is shown in the bar under the input. For reading files, the default (Auto) is fine. The section on staying read-only below covers the other modes.

Two flags help when the files you want are not under the folder you are in. Both come from safeguard --help:

# start in another folder without cd-ing there first
safeguard -C ~/code/payments-api

# start in your project, and also let the agent read another folder
safeguard --add-dir ~/Downloads

--add-dir is repeatable, so you can grant two or three extra folders for a session and nothing else.

Find and read files, step by step

The interactive terminal docs describe the assistant simply: it has tools for local files and for your Safeguard data, and it chooses whichever one a question needs. You do not pick a tool. You ask the question, and you get better answers when the question carries the details a search needs.

Walkthrough 1: find a file when you only remember something about it

1. Ask the question the way you would ask a colleague. The docs use this example, and it is a good first test:

what's the latest file in ~/Downloads

2. Add the details you do remember. File type, a word inside it, roughly when it changed, roughly how big it is. Each detail removes a lot of noise.

find the file where the payment request timeout is set
list every Dockerfile in this repo and the base image each one starts from
which files changed in the last two days under src/
show me files larger than 10 MB under ./logs, biggest first
which files import lodash, and which functions do they use from it

3. Watch what it does. To answer, the assistant may read files directly or run a read-only command such as a directory listing or a text search. In Auto, the default, read-only commands run without a prompt. In Ask mode, reads still run but commands ask first, so you will see a prompt you can accept or decline.

4. Ask for the answer, not just the paths. "Find the timeout" is a search. "Find the timeout, tell me its current value and which environment overrides it" is the question you actually had. The assistant can read the files it found and answer that in the same turn.

5. Narrow if the result is too broad. If you get forty matches, say which ones matter: "only the ones under services/billing" or "ignore test files". Follow-ups keep the context, so you do not need to repeat the first question.

Walkthrough 2: read, summarise and explain a file

1. Attach the file with @. Type @ and a picker opens for the folder you started in. It shows five entries at a time. Use the arrow keys to move, enter to choose and esc to close. The chosen file is attached to your message so the assistant can read it.

2. Ask a specific question about it.

@config/settings.yaml explain what this configures and which values I would change for staging
@logs/app.log summarise the errors and group them by message, most frequent first
@Makefile what does the release target actually run, step by step
@package.json which of these dependencies look like they are only used in tests

3. Write longer prompts across several lines. Press ctrl+j for a new line. It works everywhere. alt+enter also works where your terminal passes it through, and a trailing backslash followed by enter continues on the next line.

4. Keep the answer. /copy puts the last response on your clipboard, ready for a ticket, a pull request description or a message to a teammate. Normal terminal text selection works too, because the CLI does not capture the mouse.

5. Scroll back. The mouse wheel does not scroll the transcript. Use PgUp, PgDn and the arrow keys.

Attaching with @ beats pasting for two reasons. The assistant reads the real file, including the parts you would have trimmed, and you avoid pasting a long file into your terminal history.

Walkthrough 3: compare and cross-reference files

Reading two files side by side is where an assistant saves the most time, because the comparison is the tedious part.

1. Attach both files and say what kind of difference you care about.

compare @config/staging.yaml and @config/production.yaml and list the keys that differ, with both values
@docker-compose.yml which services have no healthcheck and no restart policy
does the lodash version in package.json match what package-lock.json actually resolved

2. Ask for evidence. Add "quote the lines" or "give me file and line" to any question where you will act on the answer. You can then open the file yourself and confirm in seconds.

3. Turn the answer into a checklist. "Make that a checklist I can paste into the ticket" works well after a comparison. Then /copy.

Walkthrough 4: tie files to your Safeguard findings

This is the part a plain file search cannot do. The assistant can read your files and your Safeguard data in the same conversation.

1. Scan the folder. In the interactive terminal, type /scan . to scan the current folder. When you are signed in, the SBOM and findings are uploaded to the platform, not your source code. From a normal shell, safeguard scan --dir . builds an SBOM, matches it against vulnerability databases and writes JSON results, with files such as vuln.json and license.json, under ./output.

safeguard scan --dir .
ls output

2. Ask about the results and the files together.

how many critical vulns do we have
read the newest vuln.json under ./output and list the critical findings with the manifest that declares each package
which files in this repo import the package behind the top finding

3. Keep it local when you need to. safeguard findings runs one scanner on your machine and prints a single normalized list: id, severity, title, CVE or rule, package and version, fixed version or file and line, description and remediation. Its help text says nothing leaves the machine, even when the CLI is signed in.

safeguard findings sca --dir .
safeguard findings sca --dir ./services/billing --json

4. Move from reading to fixing when you are ready. The recorded session at the end of this guide starts exactly like this: the assistant reads the finding, the files and the advisory before it proposes a change. Any edit or command after that goes through your approval mode.

Keep it read-only when you only want answers

Reading is safe by design in every mode, but some days you want a guarantee that nothing will change. The CLI gives you three layers.

Pick a quieter or stricter mode. These are the modes /permissions offers in the interactive CLI, as verified on CLI v11.11.0:

There is also a --yolo flag that approves everything. Keep it for throwaway sandboxes only. It has no place on a laptop with real files.

Start a restricted session. The --restricted flag runs the agent with a read-only tool set: no writes, no shell and no network. It is the simplest way to say "look, don't touch".

safeguard --restricted

Fence off folders you never want read. --disallowedTools takes deny rules in the policy syntax, and the CLI's own help uses this exact example:

safeguard --disallowedTools 'Read(~/.ssh/**)'

The flag is repeatable, so you can add a rule for each folder that holds keys or personal documents. Combine the layers when it matters:

safeguard --restricted --add-dir ~/Downloads --disallowedTools 'Read(~/.ssh/**)'

Keep a sensitive lookup out of history. --private tells the CLI not to record the run in the session store. Use it for a one-off question about a file you would not want to see again in /resume.

Ask about files 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 other devices can send work to it. That means a file question does not have to wait until you are back at your desk. From the desktop or phone app you pick the computer running the CLI and a folder, then approve each command and file edit on that computer's behalf. See the desktop app guide for setup.

This recorded desktop session shows the flow. The CLI session appears 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 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 phone works the same way. In this recorded Android session, the same conversations appear on the phone, "Work on my computer" picks a computer running the CLI and a folder, and the command waits for Allow once, Allow for turn or Deny on the phone. The answer shows the tests passed. For file questions, that means you can ask "what changed in CHANGELOG.md this week" from a corridor and read the answer on the screen in your hand. The Android guide covers installing the app.

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

Two CLI commands round this out. safeguard inbox shows what your other devices sent to this CLI, including links, text, files and conversations. safeguard send sends a link or text to one of your other signed-in devices, and safeguard devices lists the devices that can send and receive.

safeguard devices
safeguard inbox
safeguard send --help

Troubleshooting and common mistakes

Troubleshooting

The @ picker does not show the file. The picker lists the folder you started in. Either restart from the right folder with safeguard -C path/to/folder, or ask for the file by its path in plain English.

The assistant says it cannot read a path. If a folder is outside what the session may read, restart with --add-dir path/to/folder. Check that a --disallowedTools rule you set earlier is not the thing blocking it.

Every search asks for approval. You are probably in Ask mode, where commands ask first. Type /permissions and choose Auto or Accept edits if that suits the task. The bar under the input shows the mode in effect.

Questions about findings come back empty. Check you are signed in with /whoami. An empty answer means nothing matched in your active scope. It is not proof that nothing exists elsewhere. Run /scan . first if the folder has never been scanned.

"Not authenticated" or a 401. From a shell, run safeguard whoami, then safeguard logout and safeguard login --force. The CLI does not read an API key from the environment.

Something else is wrong. Run safeguard doctor and read the lines in order. Every run writes a log to ~/.sg/logs/safeguard.log, which is the file to attach if you contact support with safeguard support bug "what you ran, what you expected, what happened".

No colour in the terminal. Colour is turned off when NO_COLOR is set, when output is piped, with TERM=dumb and in CI. Check NO_COLOR in your shell profile.

Common mistakes

• Starting in your home folder. The session can then reach far more than the task needs. Start in the project and use --add-dir for the one extra folder.
• Pasting a long file into the prompt. Use @ instead. The assistant reads the real file and your terminal history stays clean.
• Acting on an answer without checking the lines. Ask for file and line, then look. It takes seconds and catches the rare wrong guess.
• Using --yolo to stop prompts. If prompts slow you down while reading, choose Accept edits or Auto. Keep --yolo for throwaway sandboxes.
• Expecting /resume to follow you between folders. It resumes the last session in the folder you start in.
• Forgetting the model sees what it reads. To answer a question about a file, the assistant has to read it, so the text becomes part of the conversation with the model you picked in /model. Keep keys and personal files out of reach with deny rules.

FAQ

Can the Safeguard CLI read files outside my project folder?

Yes, when you allow it. The docs use "what's the latest file in ~/Downloads" as an example question. For predictable results, start in your project and add extra folders with --add-dir, or start somewhere else with -C.

Does it ask before it reads a file?

Reads run without a prompt in Ask, Accept edits, Plan and Auto. What changes between modes is how commands and edits are handled. If you want no changes possible at all, start with --restricted.

Can I use my Claude or ChatGPT plan for this?

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. Use /model to see or switch the model, and see the CLI docs for connecting one. You can also connect Claude to the Safeguard MCP server and ask about your Safeguard data from Claude itself.

Does reading a file upload my code to Safeguard?

Scans upload only SBOMs and findings, never your source. When you ask the assistant about a file, it reads the file to answer, so that text is part of your conversation with the model you selected. Use deny rules and --private for anything sensitive.

Can it change a file once it has read it?

Yes, with your approval. The assistant can write files, edit code and run commands, and those actions ask before they act according to your /permissions mode.

Can I ask about files on my laptop from my phone?

Yes, while the CLI is running on that laptop. In the phone app, choose "Work on my computer", pick the computer and folder, and approve any command with Allow once, Allow for turn or Deny.

Is there a one-shot version for scripts?

safeguard exec "your question" runs one assistant turn without prompting and exits. Its default mode is strict, so anything the policy file has not pre-approved is denied, and it refuses to run outside a git repository unless you pass --skip-git-repo-check. See running the CLI in CI with safeguard exec.

How do I keep it away from my SSH keys and personal folders?

Start the session with deny rules such as --disallowedTools 'Read(~/.ssh/**)', repeated for each folder you want fenced off, and start in the project rather than your home folder.

Try it yourself

This recorded session is a real CLI run on a sample project called payments-api. It installs with the curl command (checksum verified), runs safeguard --version, and opens the interactive terminal with safeguard. It then 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. It finishes with /permissions, /model and /scan ..

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

Ready to try it on your own files? Get the CLI, the desktop app and the phone apps from safeguard.sh/download, and keep the CLI docs open for the full command list. Start in one project folder, type @, and ask the first question you would normally answer with ten minutes of searching.

Quick check

Sources

• Safeguard CLI overview
• Safeguard CLI interactive terminal
• Safeguard CLI slash commands
• Safeguard CLI usage guide
• Safeguard CLI troubleshooting
• Safeguard downloads

Last reviewed: 21 October 2026.