Attach files with @ mentions in the Safeguard CLI

To attach a file in the Safeguard CLI, type @ while writing your message. A picker opens for the folder you started the terminal in. Move with the arrow keys, press enter on the file you want, and it is attached to your message so the assistant can read it. Press esc to close the picker without choosing.

You can do all of this with 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 would rather stay in the chat app you use today, connect Claude or ChatGPT to the Safeguard MCP server and ask about your projects there.

What you will have at the end

After this guide you will be able to:

• Attach the exact file you mean with @, instead of hoping the assistant finds the right one.
• Start the terminal in the right folder so the picker shows what you need, and reach files elsewhere with --add-dir or -C.
• Use attachments for real work: fixing a vulnerable dependency, explaining scan output, reviewing a change and checking an SBOM.
• Attach screenshots with -i and pipe text into safeguard exec for one-off and CI tasks.
• Keep sensitive files out of the conversation with deny rules and a read-only mode.
• Know what attaching does not change: edits and commands still ask first, according to your approval mode.

The examples use payments-api, the sample Node.js project from our recorded demos.

How @ attachments work

The Safeguard docs describe @ as "not a command, but it behaves like one". Here is the behaviour, from the interactive terminal and slash command docs.

1. Typing @ opens a file picker. It lists files from the folder you started the terminal in.
2. The picker shows five entries at a time and scrolls to follow your selection.
3. ↑ and ↓ move, enter chooses, esc closes. The same keys work in the / command palette.
4. The picker does not hide the conversation while it is open, so you can still read the last answer as you choose.
5. The file you choose is attached to your message so the assistant can read it.

Three points follow from that.

The starting folder sets the scope. If you open the terminal in ~/code, the picker starts from ~/code, not from the project you meant. Start in the project root.

Attaching is about reading, not permission to change. An attached file is something the assistant can read. Writing a file, editing code and running a command still ask before they act, according to the mode you set with /permissions.

@ is a precision tool, not the only way in. The assistant has tools for your local files and for your Safeguard data, and picks whichever a question needs. The docs' own example is "what's the latest file in ~/Downloads". You can name a path in plain text and the assistant can go and read it. @ removes the guesswork when there are three files called config.json or when you want the assistant to start from one specific file.

Ways to give the assistant a file

Step by step walkthroughs

1. Attach a manifest and fix a vulnerable dependency

This is the most common use. You want the assistant to work from the real manifest and lockfile, not from a guess.

1. Start in the project root.

   cd ~/code/payments-api
   safeguard
   

2. Sign in and scan, if you have not already:

   /login
   /scan .
   

3. Write the request and attach the manifest. Type the start of your message, then @, pick package.json, and finish the sentence:

   fix the lodash CVE in this repo. Start from @package.json and check the lockfile too.
   

   To bring in a second file, type @ again and pick package-lock.json. The npm docs describe the lockfile as recording "the exact tree that was generated", which is why it matters as much as the manifest.

4. Read each proposed action. The assistant reads the finding, the files and the advisory, then asks before each command. In the recorded session below you press y or n at each prompt.

5. Approve the install and the tests. In the recording the assistant edits package.json to lodash 4.17.21, then runs npm install and npm test with approval.

6. Read the summary. It ends with a summary and a suggested commit message. Nothing is pushed.

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

7. Commit both files. npm's docs say package-lock.json "is intended to be committed into source repositories", so commit it with package.json:

   git add package.json package-lock.json
   git commit -m "chore(deps): upgrade lodash to 4.17.21"
   

8. Scan again with /scan . to confirm the finding is gone and the upgrade did not bring in something new.

The same pattern works for other ecosystems: attach requirements.txt or pyproject.toml for Python, pom.xml or build.gradle for Java, go.mod and go.sum for Go.

2. Attach scan output and ask what matters

safeguard scan writes JSON files you can hand straight back to the assistant.

1. Run a scan from the shell.

   safeguard scan --dir .
   

   Results are JSON files under ./output, in a folder per scan, including vuln.json and license.json.

2. Open the terminal in the same project with safeguard.

3. Attach the results. The picker lists the folder you started in. If you cannot find the scan file in the picker, name its path in plain text instead:

   read the newest vuln.json under ./output and list the critical findings with the package, installed version and fix version
   

4. Ask follow-up questions against the same file, for example "which of these are direct dependencies?" or "which fix versions are patch releases?".

5. Use license.json the same way when someone asks about licence obligations.

Because the assistant also has your Safeguard data, you can compare the local file with the platform: "does this match what the platform shows for payments-api?"

3. Attach a change for review

Before you merge, attach the files that changed and ask for a focused review.

1. See what changed.

   git status
   git diff --stat
   

2. Attach the changed source file and its test. Type your request, add @ for src/routes/refund.js, then @ again for test/refund.test.js:

   review these two files for correctness and security. Check input validation on the refund amount and tell me what the test does not cover.
   

3. Ask for the missing test. The assistant can write the test file, and it asks before it writes.

4. Run a whole working tree review too. The CLI has a dedicated command for this:

   safeguard review
   safeguard review --base main
   

   safeguard review reviews the working tree changes for correctness and security, and --base diffs against a git ref instead. Use @ when you want to steer the review towards specific files. Our guide to reviewing AI generated code before merge covers the wider routine.

4. Attach an SBOM and check it

If you share SBOMs with customers or receive them from suppliers, attach the file and validate it in the same session.

1. Validate from the shell first.

   safeguard validate sbom.cdx.json
   safeguard validate sbom.cdx.json --strict -o report.json
   

   validate checks CycloneDX, SPDX and VEX documents, and --strict treats warnings as errors.

2. Attach the report and the SBOM in the terminal and ask:

   explain each validation error in plain words and propose the smallest edit to fix it
   

3. Approve the edit, then run safeguard validate again until it passes.

5. Attach a screenshot

Some problems are easier to show than describe: a failing CI page, an error dialog, a dashboard.

1. Save the screenshot into the project or somewhere you can reference.

2. Start the CLI with the image attached.

   safeguard -i ~/Desktop/ci-failure.png
   

   The flag is repeatable, so -i before.png -i after.png attaches two.

3. Ask about it, and attach the related file with @:

   this is the CI failure. Compare it with @package.json and tell me which step failed and why.
   

For a single answer without opening the terminal, combine the flag with exec:

safeguard exec -i ci-failure.png "what does this error mean and which file should I change?"

Reach files outside the starting folder

The picker is scoped on purpose, but real projects have neighbours.

• A shared config repository next door. Start with safeguard --add-dir ../shared-config. The help says it lets the agent also read that directory, and you can repeat the flag.
• Your shell is in the wrong place. Use safeguard -C ~/code/payments-api rather than changing directory and losing your place.
• A file someone sent you from another device. safeguard inbox shows what your other devices sent to this CLI, including links, text, files and conversations, and safeguard inbox open opens one item.
• A monorepo. Start in the package you are working on so the picker stays short, and use --add-dir for the shared folder you need.

The same scoping applies when you send work from another device. In the recorded desktop session, 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, the app 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.

Picking the folder there plays the same role as starting the terminal in the right folder here. The desktop app guide covers installation.

Keep sensitive files out of the conversation

Attaching a file means its contents go into the conversation. Treat that the way you would treat pasting it into a chat.

1. Do not attach secrets. Leave .env files, private keys and credential files out. If you need help with a config file that holds secrets, make a copy with the values replaced and attach that.

2. Do not rely on .gitignore for this. Git's docs describe a gitignore file as specifying "intentionally untracked files that Git should ignore". It controls what Git tracks, so do not assume it controls what an assistant can read.

3. Add deny rules for a run. The CLI accepts deny rules in its policy syntax. The help's own example:

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

   The flag is repeatable, so you can add one per folder or pattern you want kept out.

4. Use a read-only run for questions. --restricted runs with a read-only tool set: no writes, no shell, no network. That fits "explain this file" sessions.

5. Use --private for one-offs. It keeps the run out of the session store, so nothing from it is there to resume later.

Do the work properly with the Safeguard CLI

Attachments are one part of a wider loop: write and fix code with an assistant that also knows your vulnerabilities, scan what changed before you merge, and keep source on your machine.

Install

macOS and Linux:

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

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 x86_64 only). Platform guides are available, for example installing the Safeguard CLI on Linux.

First session

Run safeguard, type /login to sign in through the browser, and /scan . to scan the current folder. Then ask in plain language. To write more than one line, press ctrl+j for a newline; enter sends.

Writing and fixing code

The assistant can read your files, write files, edit code and run commands with your approval, and it can query your Safeguard data in the same conversation. That is what makes "fix the lodash CVE in this repo" a single request rather than a research project.

Using your Claude, ChatGPT or Codex plan

Bring the plan you already pay for into the CLI; Safeguard adds no extra charge for that usage, and your provider's limits and terms still apply. /model shows or switches the model, and the CLI docs cover connecting one. If you prefer the chat app, connect ChatGPT to the Safeguard MCP server and use Safeguard from there.

Approvals

/permissions sets how often the assistant asks: Ask (reads run; edits and commands ask first), Accept edits (edits in this folder and read-only commands run; other commands ask), Plan (read and plan only), Auto (read-only commands and what the policy allows run; anything else asks; the default) and Strict (pre-approved actions only, for CI). A --yolo flag approves everything; keep it for throwaway sandboxes only. Plan mode suits attachment heavy sessions where you want analysis before any change.

CI with safeguard exec

safeguard exec runs one non-interactive assistant turn and exits. Its default mode is strict, so anything the policy has not pre-approved is denied, and it needs a git repository unless you pass --skip-git-repo-check. Pipe a prompt in with -:

safeguard exec "summarise the critical findings in this repository"
cat review-request.txt | safeguard exec -

Policies and gates are evaluated in the platform, not by the CLI. See the Safeguard CLI in CI with safeguard exec. When the local runner runs platform scan jobs, your source code never leaves the machine; only SBOMs and findings are uploaded.

Troubleshooting

The file is not in the picker. The picker lists the folder you started in. Check with pwd. Restart in the project root, use -C, or name the path in plain text.

The picker closed and nothing was attached. esc closes it without choosing. Type @ again and press enter on the file.

The assistant answered about the wrong file. Two files may share a name in different folders. Write the relative path in your message, such as src/config.json.

A file in a sibling folder cannot be read. Start the CLI with --add-dir ../that-folder, or start in a parent folder that contains both.

The image did not attach. -i takes a path when you start the CLI or run exec. Check the path and quote it if it contains spaces.

exec refuses to run. It needs a git repository. Run it inside one, or pass --skip-git-repo-check for a folder you accept cannot be undone through Git.

Something still looks wrong. safeguard doctor checks environment, sign-in, tools and policy without changing anything. Read its output lines; the exit code is 0 whenever the checks ran.

Common mistakes

• Starting in your home folder. The picker then starts from your home folder too. Start in the project.
• Attaching the manifest but not the lockfile. For dependency work, the lockfile shows what is actually installed.
• Attaching secrets. Use a redacted copy, and add a --disallowedTools rule for folders that hold keys.
• Treating attach as approval. Attaching lets the assistant read. Edits and commands still go through /permissions.
• Attaching ten files for a one-line question. Attach what the question needs. More files means more to read and more noise.
• Skipping the rescan. After any dependency change, run /scan . again.
• Using --yolo because prompts feel slow. Use Accept edits for edit heavy work in one folder instead, and keep --yolo for throwaway sandboxes.

FAQ

How do I attach a file in the Safeguard CLI?

Type @ in the interactive terminal. A picker opens for the folder you started in. 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.

Can I keep using my 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. You can also connect Claude or ChatGPT to the Safeguard MCP server and use Safeguard from the chat you already use.

Can I attach more than one file?

Yes. Type @ again and pick the next file. For dependency work, attaching the manifest and the lockfile together is a good habit.

Can I attach a file from another folder?

The picker covers the folder you started in. For another folder, start the CLI with --add-dir for that folder, use -C to start somewhere else, or write the path in your message.

Can I attach images?

Yes, with the -i or --image flag when you start the CLI or run safeguard exec. It is repeatable.

Does attaching a file let the assistant change it?

No. Attaching lets the assistant read the file. Writing, editing and running commands ask before they act, according to your /permissions mode.

Does an attached file leave my machine?

Its contents become part of the conversation with the model you use, so do not attach secrets. Separately, when the local runner runs platform scan jobs, source code stays on the machine and only SBOMs and findings are uploaded.

How do I give the assistant a file in CI?

Use safeguard exec. Pass the prompt as an argument or pipe it in with -, and use -i for images. Its default mode is strict.

Try it yourself

New to the CLI? This demo shows 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.

Get the CLI, desktop and mobile apps from safeguard.sh/download, and keep the CLI docs open as you try the walkthroughs.

Quick check

Sources

• Safeguard CLI documentation
• Safeguard CLI: Interactive terminal
• Safeguard CLI: Slash commands
• Safeguard CLI: Usage guide
• Safeguard downloads
• npm documentation: package-lock.json
• Git documentation: gitignore

Last reviewed: 21 October 2026.