Skip to main content

Command line (CLI)

The guardkite command line tool reads your findings, fixes, and decisions from a terminal. It suits scripts, quick lookups, and coding agents that run shell commands.

It signs in as you and can do exactly what you can do in the web app, no more. A Member can read; only someone allowed to make decisions in the web app can make them from the CLI.

Install​

The CLI installs with uv, which also fetches a suitable Python if you don't have one.

uv tool install guardkite --index https://platform.guardkite.com/cli/simple/

If your organization signs in to GuardKite at a different address, use that address in place of platform.guardkite.com. The CLI you install there connects to that address.

Upgrade and uninstall​

  • Upgrade with uv tool upgrade guardkite. Once a day, the CLI tells you when a newer version is available.
  • Remove it with uv tool uninstall guardkite.

If GuardKite stops supporting your version, commands stop with a message asking you to upgrade.

Sign in​

Run guardkite login. It prints an address and a short code:

Open https://platform.guardkite.com/cli and enter LRZX-FHTV
  1. Open the address in a browser where you're signed in to GuardKite.
  2. Enter the code, check the details shown (time, IP address, operating system), and choose Approve.
  3. The terminal prints Signed in.

Only approve a code you started yourself in the last few minutes. If you didn't start it, choose Deny.

Where your session is stored​

The CLI keeps your session in your system keychain. Where there is no keychain, it uses a file in your user configuration folder that only you can read, and tells you so.

One organization per session​

A CLI session works in the organization you were in when you approved it.

If you work across organizations (for example as a partner or GuardKite staff in a support session), approve the sign-in from inside the organization you want. Leaving or switching that organization in the browser ends the CLI session; run guardkite login again.

Seeing and ending sessions​

  • Your Profile page lists your CLI sessions, with the organization, CLI version, and when each was last used. Revoke ends one.
  • guardkite logout signs out and forgets the stored session.
  • An unused session ends after 7 days, and every session ends 30 days after sign-in.

Commands​

CommandWhat it shows
guardkite whoamiYour name, email, role, and organization.
guardkite accountsYour AWS accounts and when each was last checked and last fully scanned.
guardkite findings summaryFailing findings counted per check, most severe first.
guardkite findings listFailing findings, filtered with --account, --region, --severity, --category, or --search.
guardkite findings check CHECK_IDOne check: what it tests, where to fix it in the AWS console, and the resources failing it.
guardkite findings resource RESOURCE --account ID --region REGIONEvery check evaluated against one resource. Add --check CHECK_ID for one check with its fix.
guardkite findings changesFindings that started or stopped failing in the last 7 days. Use --days to look further back.
guardkite fixes listThe fixes that close the most attack paths, best first.
guardkite fixes show SIGNATUREOne fix and the attack paths it closes.
guardkite dispositions listYour decisions in force: what is marked won't fix or snoozed.

Every command has --help. For example, guardkite findings list --help lists its filters.

Long lists​

Lists show 50 rows by default. Use --limit for a different number or --all for everything. When there are more rows, the CLI says so.

Make a decision from the CLI​

A decision marks a finding or fix as won't fix (an accepted risk) or snoozed until a date. It is the same decision you can make on the Findings and Attack Paths pages.

The key comes from the Key column of findings list, findings check, or fixes list.

guardkite dispositions set KEY --wont-fix --reason "Public by design: static website bucket"
guardkite dispositions set KEY --snooze-until 2026-12-31 --reason "Fix scheduled in the next release"
guardkite dispositions clear KEY
  • A reason is required and is kept with the decision.
  • --snooze-until takes a date (the end of that day, your local time) or a full date and time.
  • In a terminal, the CLI shows what it will do and asks you to confirm. Outside a terminal, add --yes.
  • In the web app, a decision made from the CLI is labeled via CLI.

Scripts and coding agents​

  • Add --json to any command for JSON output. It works before or after the command.
  • When output goes to a file or another program instead of a terminal, tables print as tab-separated lines, with every value in full.
  • Messages such as "Showing the first 50 findings" go to standard error, so they never mix with the data.

Exit codes​

CodeMeaning
0Success.
1Something went wrong, for example GuardKite couldn't be reached.
2The command line was wrong, for example a missing option, or a decision without --yes outside a terminal.
3Not signed in, or the session ended. Run guardkite login.
4Your role doesn't allow this.
5This version of the CLI is no longer supported. Run uv tool upgrade guardkite.

Unattended access​

The CLI always signs in as a person, through the browser. For a system that reads GuardKite on its own, use a service user instead.