Reference

CLI

Install, authenticate, manage credentials, authorize resources, and run commands in secure sessions with Keycard.

The keycard CLI handles authentication, credential management, resource authorization, and secure agent sessions.

Install

brew install keycardai/tap/keycard

Verify the installation:

keycard version

Install plugin

Install the Keycard plugin for Claude Code:

keycard plugin install

The plugin includes a set of Skills Claude uses to manage credentials, query policy, and update keycard.toml.

Pull down the latest version of the plugin at any time:

keycard plugin update

Supported platforms

The Keycard CLI supports macOS and Linux on both amd64 and arm64 architectures.

Update

Update to the latest version with Homebrew:

brew upgrade keycard

Authentication

Sign into your Keycard account. The CLI opens an OIDC browser sign-in flow and stores the resulting tokens in your system keyring.

keycard auth signin --zone <zone-id> --org <org-id>

Flag	Description
`-z`, `--zone`	Zone ID. Falls back to `ZONE` or `zone.id` in `keycard.toml`
`-o`, `--org`	Organization ID

Check your current identity:

keycard auth whoami --zone <zone-id>

Sign out and remove stored tokens. Accepts -z/--zone and -o/--org:

keycard auth signout --zone <zone-id>

Resource authorization

Authorize access to one or more Resources. The command also initiates sign-in if you don’t have an active session.

keycard auth resource <uri>... --zone <zone-id>

Use this when a tool reports that resource access requires authorization.

Running commands

Run a command inside a Keycard secure session to provision just-in-time credentials and enforce policy on tool use.

keycard run --zone <zone-id> -- <command>

Flag	Description
`-z`, `--zone`	Zone ID. Falls back to `ZONE` or `zone.id` in `keycard.toml`
`--itl-prompt`	In-the-loop prompter backend: `osascript`, `browser`, or `native`. Also settable via `ITL_PROMPT`

Credentials are sourced from [[credentials.default]] entries in keycard.toml. See Configuration for details.

To run Claude Code inside a secure session, use the dedicated subcommand:

keycard run claude --zone <zone-id>

The policy enforced on tool use comes from your local policy file. Platform-Managed Policy (coming soon) distributes and enforces that policy centrally from your Zone instead.

Session environment variables

Inside a secure session, the following environment variables are set automatically:

KEYCARD_RUN=1: indicates the process is running inside a Keycard session.
KEYCARD_RUN_SESSION_ID: the unique session identifier.

Credentials

Get an access credential for a Resource URI:

keycard credential read <uri> --zone <zone-id>

The URI must be present in the default credential set. Configure it in keycard.toml first.

List all credential entries configured in keycard.toml that would be hydrated by keycard run:

keycard credential info

Add a gateway credential entry, or sync credential configuration down from your Zone:

keycard credential add
keycard credential sync

Configuration

Config file

The CLI loads configuration from keycard.toml in the current directory. Override the path with --config or CLI_CONFIG.

[zone]
id = "<zone-id>"

[[credentials.default]]
env_var = "GH_TOKEN"
resource = "https://api.github.com"

Global flags

Flag	Description
`--config`	Configuration file path. Defaults to `keycard.toml`
`-h`, `--help`	Show help for a command

The Zone ID is resolved from --zone, then the ZONE environment variable, then zone.id in keycard.toml. Commands that need a Zone fail with an explicit error if none of the three is set.

Commands

Command	Description
`keycard run`	Run a command in a Keycard secure session
`keycard run claude`	Run Claude Code in a Keycard secure session
`keycard auth signin`	Authenticate with your account
`keycard auth signout`	Remove local authentication tokens
`keycard auth whoami`	Identify the current account
`keycard auth resource`	Authorize access to Resources
`keycard credential read`	Read a credential for a URI
`keycard credential info`	Show configured credential identifiers
`keycard credential add`	Add a gateway credential entry
`keycard credential sync`	Sync credential configuration from your Zone
`keycard plugin install`	Install the Keycard plugin for Claude Code
`keycard plugin update`	Update the Keycard plugin for Claude Code
`keycard version`	Show version info. Accepts `--json`

Agent commands

Command	Description
`keycard agent hook`	Process agent hooks
`keycard agent policy`	Print the active Cedar policy
`keycard agent exec`	Run a command with credentials injected
`keycard agent api`	Make an authenticated Management API request

Agent hooks

Process hook events from AI agents (Claude Code, Cursor, and others).

keycard agent hook <agent>

Agent policy

Print the Cedar policy currently in effect, including its @description, @credentials, and @itl annotations:

keycard agent policy

When policy is managed on the platform, this prints the version resolved for the session. See Platform-Managed Policy.

Agent exec

Run a command with credentials hydrated from [[credentials.default]] entries in keycard.toml. Unlike keycard run, this fails immediately if any credential requires interactive authentication. Safe for use in non-interactive agent subprocesses.

keycard agent exec --zone <zone-id> -- <command>

Inside an agent exec subprocess, KEYCARD_AGENT_EXEC=1 is set automatically.

Agent API

Make an authenticated HTTP request to the Keycard Management API and print the response body to stdout.

Flag	Description
`-X`, `--method`	HTTP method. Defaults to `GET`
`-d`, `--data`	JSON request body. Reads stdin if omitted
`-o`, `--org`	Organization ID
`-z`, `--zone`	Zone ID

keycard agent api <endpoint>

Use -X to override the HTTP method (default: GET):

keycard agent api <endpoint> -X POST

Use -d to pass a JSON request body (reads stdin if omitted):

keycard agent api <endpoint> -X POST -d '{"key":"value"}'

Use -o / --org to specify an organization ID:

keycard agent api <endpoint> --org <org-id>