---
title: CLI | Keycard
description: 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.

Tip

Set your zone.id in a `keycard.toml` file to avoid passing `--zone` on every command. See [Configuration](#configuration) below.

## Install

Terminal window

```
brew install keycardai/tap/keycard
```

Verify the installation:

Terminal window

```
keycard version
```

### Install plugin

Terminal window

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

The plugin includes a set of [Skills](/skills/index.md) 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:

Terminal window

```
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.

Terminal window

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

Check your current identity:

Terminal window

```
keycard auth whoami --zone <zone-id>
```

Sign out and remove stored tokens:

Terminal window

```
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.

Terminal window

```
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.

Terminal window

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

Credentials are sourced from `[[credentials.default]]` entries in `keycard.toml`. See [Configuration](#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:

Terminal window

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

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

Terminal window

```
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

Caution

Commands under `keycard agent` are designed to be invoked by AI agents and automated tooling, not directly by humans. They assume a non-interactive environment and may behave unexpectedly when run manually. Use the top-level commands (`keycard run`, `keycard auth`, `keycard credential`) for interactive use instead.

### Agent Hooks

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

Terminal window

```
keycard agent hook --claude
```

Print the active Cedar policy:

Terminal window

```
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.

Terminal window

```
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.

Terminal window

```
keycard agent api <endpoint>
```

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

Terminal window

```
keycard agent api <endpoint> -X POST
```

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

Terminal window

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

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

Terminal window

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