On a server with no browser, run the CLI login command with the no browser option. It prints a URL and a short code. Open the URL on any device, enter the code, and the CLI receives its token. The documentation says there is no API key variable, so a machine is authorized by signing in once.
How the flow works
The login command uses the OAuth 2.0 device authorization flow, defined in RFC 8628. In plain terms:
- The CLI asks the auth service for a device code.
- You open a verification URL on another device and enter the code.
- The CLI polls until you approve, then saves its tokens locally.
Nothing is typed into the headless machine except the command itself, which is why this flow suits SSH sessions and containers.
The commands
safeguard login --no-browser
Check the result and the token expiry:
safeguard whoami
Sign out, which revokes the session and removes the local token:
safeguard logout
If the machine is already signed in and you want a different account, add the force option to the login command.
Stop the browser trying to open
Two ways to avoid a browser launch attempt: use the no browser option on the command, or set the no browser variable in the environment. The second is handy for the interactive terminal, where sign-in happens through a slash command inside the session.
Where the token lives
The configuration docs say the sign-in token is stored in ~/.scanner/token.json and is readable only by you by default. A credential store setting lets you choose a file, the operating system store, or automatic selection.
Treat that file like an SSH key:
- Do not copy it between machines.
- Do not bake it into an image.
- Do not commit the home directory of a build agent.
What about CI?
The documentation states the CLI does not read an API key from the environment. That shapes CI design. Options the docs describe are connecting the repository so the platform runs the scan, or running the CLI on a runner that has been signed in once. For ephemeral runners, the scan and detect commands run locally and write files, so they do not need a signed-in session to produce results, but uploading to the platform does.
If your pipeline needs unattended uploads, check with your Safeguard administrator which method your account supports, because a build of the CLI may offer more than the public pages describe.
Troubleshooting
- Not authenticated or HTTP 401. The token expired or is missing. Run the whoami command, then log out and log in again with the force option.
- Sign-in never finishes. Use the no browser option and finish the step on another device.
- Network errors. Check proxy settings and outbound HTTPS on port 443.
Quick check
Can I use an API key instead of signing in?
The public documentation says the CLI reads no API key from the environment. Sign in with the login command.
Where is the token stored?
In a file under your home directory named token.json inside the scanner folder, readable only by your user by default.
You can try a scan without signing in anywhere using the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
