Installing and using the Patrol CLI

The Patrol CLI (patrol) lets you connect cloud accounts to Patrol from the command line — automating the IAM role and service principal setup that would otherwise require manual steps in the cloud console.

Installation

The CLI is distributed as an npm package:

npm install -g @patrol/cli

Verify the installation:

patrol --version

Prerequisites

Which cloud tools you need depends on what you’re connecting:

Cloud	Prerequisite
AWS	AWS CLI configured with credentials for the target account
Azure	Azure CLI (`az login` completed)
GCP	gcloud CLI authenticated with the target project

Authentication

Before connecting cloud accounts, log in to your Patrol instance:

patrol login

This prompts for your Patrol API URL and credentials, then stores a token locally for subsequent commands.

To log out and remove the stored token:

patrol logout

Connecting cloud accounts

The fastest path is to use the setup command generated directly from Patrol’s UI. On any cloud account’s detail page, click Generate setup command — this produces a one-time token baked into a ready-to-run command.

AWS

# Using the one-time token from Patrol's UI (recommended)
patrol connect aws --token <token>

# Without a token — prints credentials for you to enter manually
patrol connect aws

What it does:

Creates (or updates) an IAM role — default name PatrolReadOnly
Attaches SecurityAudit and ViewOnlyAccess managed policies
Sets a trust policy scoped to Patrol’s AWS account with an sts:ExternalId condition (confused-deputy protection)
Reports the Role ARN back to Patrol automatically (when using --token)

Options:

--profile <name> — AWS profile to use (defaults to the AWS CLI default)
--role-name <name> — IAM role name (defaults to PatrolReadOnly)

Azure

# Using the one-time token from Patrol's UI (recommended)
patrol connect azure --token <token>

# Without a token — prints credentials for you to enter manually
patrol connect azure

What it does:

Creates a Service Principal (default name PatrolReadOnly) with the Reader role on the subscription
Generates a client secret
Saves the credentials back to Patrol automatically (when using --token)

Options:

--subscription <id> — Azure subscription ID (defaults to the current az CLI subscription)
--sp-name <name> — Service Principal display name (defaults to PatrolReadOnly)

See Connecting Azure accounts for a full walkthrough.

Setting up Azure deployment prerequisites

If you’re deploying to Azure via Terraform, the CLI can provision the Azure-side infrastructure Patrol needs:

patrol setup azure

This creates:

A resource group (patrol-infra) for Patrol infrastructure
A storage account with a tfstate container for Terraform state
A Service Principal with Contributor role and OIDC federated credentials for GitHub Actions

Options:

--subscription <id> — Azure subscription ID
--region <region> — Azure region (defaults to uksouth)
--storage-account <name> — storage account name
--repo <org/repo> — GitHub repository that will deploy

One-step register and connect

patrol register combines adding the cloud account to Patrol and setting up cloud access in a single command:

patrol register aws
patrol register azure

This is equivalent to adding the account in Patrol’s UI and then running patrol connect, all in one step.