CLI | Keycard

Reference

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

claude plugin marketplace add keycardai/plugins
claude plugin install keycard-cli@keycardai

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

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 by opening an OIDC browser sign-in flow and storing tokens securely in your system keyring.

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

Check your current identity:

keycard auth whoami --zone <zone-id>

Sign out and remove stored tokens:

keycard auth signout --zone <zone-id>

Resource Authorization

Authorize access to one or more resources, also initiate sign-in if you don’t have an active session.

keycard auth resource <uri> [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>

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

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>

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

keycard credential info

Configuration

Config file

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

[zone]
id = "your-zone-id"

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

Commands

Command	Description
`keycard run`	Run a command 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`	List credential entries from keycard.toml
`keycard version`	Show version info

Agent Commands

Agent Hooks

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

keycard agent hook --claude

Print the active Cedar policy:

keycard agent 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.

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>