CLI

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

brew install keycardai/tap/keycard

Verify the installation:

keycard version

Install the Keycard plugin for Claude Code:

keycard plugin install

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

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

keycard plugin update

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

Update to the latest version with Homebrew:

brew upgrade keycard

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>

The default sign-in opens a browser on the machine running the CLI and listens on a localhost port for the redirect back. That only works when the browser and the CLI share a machine. Over SSH, inside a container or devcontainer, on a cloud development VM, or on a build agent, there is no browser to open, and a redirect to localhost lands on the remote host where nothing can reach it.

The device authorization flow (RFC 8628) removes both requirements. The CLI prints a short code and a URL. You open the URL on any device with a browser, such as your laptop or phone, enter the code, and approve the sign-in. The CLI polls Keycard in the background and continues as soon as the code is approved. Nothing has to connect back to the remote machine, and no port is opened on it.

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

The CLI prompts for two codes: the first signs you into your Keycard account, the second signs you into the Zone. Each prompt shows its own code and URL.

* Waiting for authorization…
| Enter this code: ABCD-EFGH
| Open: https://<keycard-issuer-url>/device
| Or press Enter to open automatically

If a browser is available on the machine, press Enter to open the URL with the code prefilled. Otherwise, type the URL into a browser elsewhere and enter the code by hand. Each code expires after a few minutes; if it does, re-run the command to get a new one.

Set KEYCARD_DEVICE=1 in the environment to use the device flow by default, for example in a container image or a shell profile on a remote host. The tokens are stored in the same system keyring as a browser sign-in, so every other keycard command works the same way afterwards.

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>

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.

Run a command inside a Keycard secure session to provision just-in-time credentials.

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

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>

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.

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

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"

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.

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

keycard agent hook <agent>

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.

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>