turnkey_tk 0.4.1

# Command reference

Do not edit by hand: this file is autogenerated with

```
TK_UPDATE_COMMANDS_MD=1 cargo test commands_reference
```

This lists what the parser accepts. Validation that happens after parsing,
such as identity resolution or JSON shape checks, and the Git and GPG shim
modes that bypass this parser are described in the area docs.

## `tk`

CLI for Turnkey backed auth workflows

```
CLI for Turnkey backed auth workflows.

Commands may prompt when stdin is a TTY. Pass --non-interactive or set
TK_NON_INTERACTIVE=true to fail fast instead.

--message-format json prints one JSON record per line, each with a `reason`
field; error records also carry a `code`. JSON output never prompts.

Record shapes and error codes: `tk skills show --name references/cli-convention`.
Exit codes: 0 success, 1 runtime error, 2 usage error.
```

```
tk [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk activity`](#tk-activity): Manage activities and their approvals
- [`tk ssh`](#tk-ssh): Manage SSH keys held in Turnkey and serve them to SSH and Git
- [`tk request`](#tk-request): Send an arbitrary signed API request
- [`tk user`](#tk-user): Manage users and user tags
- [`tk policy`](#tk-policy): Manage policies and inspect evaluations
- [`tk api-key`](#tk-api-key): Manage registered API credentials
- [`tk wallet`](#tk-wallet): Manage wallets and accounts
- [`tk sign`](#tk-sign): Sign payloads and serialized transactions
- [`tk secret`](#tk-secret): Manage encrypted secrets
- [`tk session`](#tk-session): Rotate short-lived credentials for agent profiles
- [`tk gpg`](#tk-gpg): Sign with PGP keys backed by wallet accounts
- [`tk skills`](#tk-skills): Serve the embedded turnkey-tk agent skills
- [`tk login`](#tk-login): Verify a saved profile with Turnkey and select it
- [`tk whoami`](#tk-whoami): Verify the selected identity with Turnkey
- [`tk auth`](#tk-auth): Manage API authentication
- [`tk profile`](#tk-profile): Manage named API identities

### Global options

Every command accepts these.

| Argument | Notes | Description |
|---|---|---|
| `--profile <PROFILE>` | env `TK_PROFILE` | Named profile to use from the identity registry |
| `--organization-id <ORGANIZATION_ID>` |  | Override the organization the command operates on |
| `--api-base-url <API_BASE_URL>` |  | Override the API base URL |
| `--non-interactive` | env `TK_NON_INTERACTIVE` | Disable interactive prompts and fail fast when required values are missing |
| `--message-format <MESSAGE_FORMAT>` | default `human`; one of `human`, `json` | Format user-facing output |
| `--color <COLOR>` | default `auto`; one of `auto`, `always`, `never` | Control ANSI color in user-facing output |

```
API identity:
  Without --profile, resolved from exactly one source: the
  TURNKEY_ORGANIZATION_ID, TURNKEY_API_PUBLIC_KEY, TURNKEY_API_PRIVATE_KEY
  environment bundle; else the registry's active profile.
  The profile registry lives at ~/.config/turnkey/tk.config.toml.
  TURNKEY_API_BASE_URL overrides the API endpoint.

SSH agent:
  tk ssh agent start
  export SSH_AUTH_SOCK=~/.config/turnkey/ssh-agent.sock

Skills:
  tk skills install --into DIR
  Writes the turnkey-tk package embedded in this binary as DIR/turnkey-tk;
  start from its SKILL.md. The same package is published at
  https://github.com/tkhq/tk/tree/main/skills.
```

### `tk activity`

Manage activities and their approvals

```
tk activity [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk activity list`](#tk-activity-list): List activities, one page at a time
- [`tk activity get`](#tk-activity-get): Fetch one activity by ID
- [`tk activity approve`](#tk-activity-approve): Approve a `pending` activity by ID
- [`tk activity reject`](#tk-activity-reject): Reject a `pending` activity by ID
- [`tk activity wait`](#tk-activity-wait): Poll one activity until it reaches a terminal status

#### `tk activity list`

List activities, one page at a time

```
tk activity list [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--limit <LIMIT>` | default `50` | Page size |
| `--cursor <CURSOR>` |  | Activity ID to continue after |
| `--status <STATUS> (repeatable)` | one of `pending`, `completed`, `rejected`, `failed` | Keep only these statuses, filtered by the server; repeatable. pending matches created, pending, consensus-needed, and authenticators-needed activities |
| `--type <ACTIVITY_TYPE> (repeatable)` |  | Keep only these activity types, filtered by the server, such as `ACTIVITY_TYPE_CREATE_USER_TAG`; repeatable |
| `--since <DURATION>` |  | Keep only activities created within this window, such as 24h, filtered here: walks pages newest first from --cursor until one is older; --limit caps the matches and sets nextCursor so the same command with --cursor resumes |

#### `tk activity get`

Fetch one activity by ID

```
tk activity get [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Activity ID |

#### `tk activity approve`

Approve a `pending` activity by ID

```
tk activity approve [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Activity ID |

#### `tk activity reject`

Reject a `pending` activity by ID

```
tk activity reject [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Activity ID |

#### `tk activity wait`

Poll one activity until it reaches a terminal status

```
tk activity wait [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Activity ID |
| `--timeout <TIMEOUT>` | default `60` | Seconds to poll before failing with `wait_timeout` |

### `tk ssh`

Manage SSH keys held in Turnkey and serve them to SSH and Git

```
tk ssh [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk ssh keys`](#tk-ssh-keys): Manage registered Ed25519 private keys
- [`tk ssh public-key`](#tk-ssh-public-key): Print a registered SSH public key
- [`tk ssh git-sign`](#tk-ssh-git-sign): Sign a payload using the Git SSH signer interface
- [`tk ssh agent`](#tk-ssh-agent): Manage a background SSH agent over a Unix socket

#### `tk ssh keys`

Manage registered Ed25519 private keys

```
tk ssh keys [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk ssh keys create`](#tk-ssh-keys-create): Create an Ed25519 private key in Turnkey and register it
- [`tk ssh keys add`](#tk-ssh-keys-add): Fetch and register an Ed25519 private key
- [`tk ssh keys list`](#tk-ssh-keys-list): List the registered SSH keys without contacting Turnkey
- [`tk ssh keys remove`](#tk-ssh-keys-remove): Forget a registered key without changing the Turnkey private key

##### `tk ssh keys create`

Create an Ed25519 private key in Turnkey and register it

```
tk ssh keys create [OPTIONS] --name <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `--name <NAME>` | required | Name of the new private key |

##### `tk ssh keys add`

Fetch and register an Ed25519 private key

```
tk ssh keys add [OPTIONS] --private-key-id <PRIVATE_KEY_ID>
```

| Argument | Notes | Description |
|---|---|---|
| `--private-key-id <PRIVATE_KEY_ID>` | required | Turnkey private key to register |

##### `tk ssh keys list`

List the registered SSH keys without contacting Turnkey

```
tk ssh keys list [OPTIONS]
```

##### `tk ssh keys remove`

Forget a registered key without changing the Turnkey private key

```
tk ssh keys remove [OPTIONS] <KEY>
```

| Argument | Notes | Description |
|---|---|---|
| `<KEY>` | required | Fingerprint, public key line, or Turnkey private key ID |

#### `tk ssh public-key`

Print a registered SSH public key

```
tk ssh public-key [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--key <KEY>` |  | Fingerprint, public key line, or Turnkey private key ID |

#### `tk ssh git-sign`

Sign a payload using the Git SSH signer interface

```
tk ssh git-sign [OPTIONS] [SSH_KEYGEN_ARGS]...
```

| Argument | Notes | Description |
|---|---|---|
| `<SSH_KEYGEN_ARGS>...` |  | Arguments Git passes to its SSH signing program, in ssh-keygen form |

#### `tk ssh agent`

Manage a background SSH agent over a Unix socket

```
tk ssh agent [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk ssh agent start`](#tk-ssh-agent-start): Start the SSH agent in the background
- [`tk ssh agent stop`](#tk-ssh-agent-stop): Stop the background SSH agent
- [`tk ssh agent status`](#tk-ssh-agent-status): Report the background SSH agent state

##### `tk ssh agent start`

Start the SSH agent in the background

```
tk ssh agent start [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--key <KEY> (repeatable)` |  | Serve only this registered key |
| `--socket <PATH>` |  | Unix socket path for SSH agent connections |
| `--pid-file <PATH>` |  | PID file path of the background SSH agent |

##### `tk ssh agent stop`

Stop the background SSH agent

```
tk ssh agent stop [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--socket <PATH>` |  | Unix socket path for SSH agent connections |
| `--pid-file <PATH>` |  | PID file path of the background SSH agent |

##### `tk ssh agent status`

Report the background SSH agent state

```
tk ssh agent status [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--socket <PATH>` |  | Unix socket path for SSH agent connections |
| `--pid-file <PATH>` |  | PID file path of the background SSH agent |

### `tk request`

Send an arbitrary signed API request

```
tk request [OPTIONS] --path <PATH>
```

| Argument | Notes | Description |
|---|---|---|
| `--path <PATH>` | required | Absolute API path under /public/v1/, such as /public/v1/query/whoami |
| `--body <BODY>` |  | Exact request body |
| `--body-file <BODY_FILE>` |  | Read exact UTF-8 request bytes from a file, or - for stdin |
| `--stamp-only` |  | Produce a stamp without submitting the request |

Constraints:

- `--body-file` conflicts with `--body`
- `--body` conflicts with `--body-file`

### `tk user`

Manage users and user tags

```
tk user [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk user list`](#tk-user-list): List users
- [`tk user get`](#tk-user-get): Fetch one user by ID
- [`tk user create`](#tk-user-create): Create a user from flags, or one or more users from a `CreateUsersIntentV4` parameters object
- [`tk user update`](#tk-user-update): Update a user from an `UpdateUserIntentV2` parameters object
- [`tk user delete`](#tk-user-delete): Delete users by ID
- [`tk user tag`](#tk-user-tag): Manage user tags

#### `tk user list`

List users

```
tk user list [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--tag <NAME_OR_ID>` |  | Keep only users carrying this tag, given as a tag ID or an exact tag name |

#### `tk user get`

Fetch one user by ID

```
tk user get [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | User ID |

#### `tk user create`

Create a user from flags, or one or more users from a `CreateUsersIntentV4` parameters object

```
tk user create [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>|--user-name <USER_NAME>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |
| `--user-name <USER_NAME>` |  | Name of the single user to create |
| `--email <EMAIL>` |  | Email of the user |
| `--tag <TAGS> (repeatable)` |  | Tag ID to attach |
| `--tag-name <TAG_NAMES> (repeatable)` |  | Tag name to attach, resolved against the organization's tags |
| `--public-key <PUBLIC_KEY>` |  | Compressed P256 public key (hex) to register as the user's API key |
| `--expires-in <EXPIRES_IN>` |  | Lifetime of that API key, for example 7d; omit for a key that never expires |
| `--anchor-key` |  | Also register a never-expiring anchor key whose private half is generated here and discarded |

Constraints:

- exactly one of `--input-json`, `--input-file`, `--user-name`

#### `tk user update`

Update a user from an `UpdateUserIntentV2` parameters object

```
tk user update [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk user delete`

Delete users by ID

```
tk user delete [OPTIONS] <IDS>...
```

| Argument | Notes | Description |
|---|---|---|
| `<IDS>...` | required | User IDs |

#### `tk user tag`

Manage user tags

```
tk user tag [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk user tag list`](#tk-user-tag-list): List user tags
- [`tk user tag create`](#tk-user-tag-create): Create a tag by name, or from a `CreateUserTagIntent` parameters object
- [`tk user tag update`](#tk-user-tag-update): Update a tag from an `UpdateUserTagIntent` parameters object
- [`tk user tag delete`](#tk-user-tag-delete): Delete tags by ID

##### `tk user tag list`

List user tags

```
tk user tag list [OPTIONS]
```

##### `tk user tag create`

Create a tag by name, or from a `CreateUserTagIntent` parameters object

```
tk user tag create [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>|--name <NAME>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |
| `--name <NAME>` |  | Name of the new tag, with no members |

Constraints:

- exactly one of `--input-json`, `--input-file`, `--name`

##### `tk user tag update`

Update a tag from an `UpdateUserTagIntent` parameters object

```
tk user tag update [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

##### `tk user tag delete`

Delete tags by ID

```
tk user tag delete [OPTIONS] <IDS>...
```

| Argument | Notes | Description |
|---|---|---|
| `<IDS>...` | required | Tag IDs |

### `tk policy`

Manage policies and inspect evaluations

```
tk policy [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk policy list`](#tk-policy-list): List policies
- [`tk policy get`](#tk-policy-get): Fetch one policy by ID
- [`tk policy create`](#tk-policy-create): Create a policy from flags, or from a `CreatePolicyIntentV3` parameters object
- [`tk policy create-batch`](#tk-policy-create-batch): Create multiple policies from a parameters object containing policies
- [`tk policy update`](#tk-policy-update): Update a policy from an `UpdatePolicyIntentV2` parameters object
- [`tk policy delete`](#tk-policy-delete): Delete policies by ID
- [`tk policy evaluations`](#tk-policy-evaluations): List the policy evaluations recorded for one activity

#### `tk policy list`

List policies

```
tk policy list [OPTIONS]
```

#### `tk policy get`

Fetch one policy by ID

```
tk policy get [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Policy ID |

#### `tk policy create`

Create a policy from flags, or from a `CreatePolicyIntentV3` parameters object

```
tk policy create [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>|--name <NAME>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |
| `--name <NAME>` |  | Name of the policy |
| `--effect <EFFECT>` | one of `allow`, `deny` | Effect of the policy |
| `--condition <CONDITION>` |  | Condition expression, evaluated against the activity |
| `--consensus <CONSENSUS>` |  | Consensus expression, evaluated against the approvers |
| `--notes <NOTES>` |  | Free-text notes stored with the policy |

Constraints:

- exactly one of `--input-json`, `--input-file`, `--name`

#### `tk policy create-batch`

Create multiple policies from a parameters object containing policies

```
tk policy create-batch [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk policy update`

Update a policy from an `UpdatePolicyIntentV2` parameters object

```
tk policy update [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk policy delete`

Delete policies by ID

```
tk policy delete [OPTIONS] <IDS>...
```

| Argument | Notes | Description |
|---|---|---|
| `<IDS>...` | required | Policy IDs |

#### `tk policy evaluations`

List the policy evaluations recorded for one activity

```
tk policy evaluations [OPTIONS] <ACTIVITY_ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ACTIVITY_ID>` | required | Activity ID |

### `tk api-key`

Manage registered API credentials

```
tk api-key [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk api-key generate`](#tk-api-key-generate): Generate a protected local credential file without registration
- [`tk api-key list`](#tk-api-key-list): List API keys
- [`tk api-key register`](#tk-api-key-register): Register public keys from a `CreateApiKeysIntentV2` parameters object
- [`tk api-key delete`](#tk-api-key-delete): Delete API keys of one user by ID

#### `tk api-key generate`

Generate a protected local credential file without registration

```
tk api-key generate [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--output <OUTPUT>` |  | New credential JSON path; defaults to a file named by the public key under ~/.config/turnkey/tk/api-keys/ |

#### `tk api-key list`

List API keys

```
tk api-key list [OPTIONS] <--user-id <USER_ID>|--all-users>
```

| Argument | Notes | Description |
|---|---|---|
| `--user-id <USER_ID>` |  | List the keys of this user |
| `--all-users` |  | List the keys of every user in the organization |
| `--expiring-within <DURATION>` |  | Keep only keys whose expiry is at most this far ahead, such as 2h or 7d |
| `--expired` |  | Keep only keys whose expiry has passed |
| `--long-lived` |  | Keep only keys that never expire |

Constraints:

- at most one of `--expiring-within`, `--expired`, `--long-lived`
- exactly one of `--user-id`, `--all-users`

#### `tk api-key register`

Register public keys from a `CreateApiKeysIntentV2` parameters object

```
tk api-key register [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk api-key delete`

Delete API keys of one user by ID

```
tk api-key delete [OPTIONS] --user-id <USER_ID> <IDS>...
```

| Argument | Notes | Description |
|---|---|---|
| `--user-id <USER_ID>` | required | User who owns the keys |
| `<IDS>...` | required | API key IDs |

### `tk wallet`

Manage wallets and accounts

```
tk wallet [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk wallet list`](#tk-wallet-list): List wallets
- [`tk wallet get`](#tk-wallet-get): Fetch one wallet by ID
- [`tk wallet create`](#tk-wallet-create): Create a wallet from a `CreateWalletIntent` parameters object
- [`tk wallet update`](#tk-wallet-update): Update a wallet from an `UpdateWalletIntent` parameters object
- [`tk wallet account`](#tk-wallet-account): Manage wallet accounts

#### `tk wallet list`

List wallets

```
tk wallet list [OPTIONS]
```

#### `tk wallet get`

Fetch one wallet by ID

```
tk wallet get [OPTIONS] <ID>
```

| Argument | Notes | Description |
|---|---|---|
| `<ID>` | required | Wallet ID |

#### `tk wallet create`

Create a wallet from a `CreateWalletIntent` parameters object

```
tk wallet create [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk wallet update`

Update a wallet from an `UpdateWalletIntent` parameters object

```
tk wallet update [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk wallet account`

Manage wallet accounts

```
tk wallet account [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk wallet account list`](#tk-wallet-account-list): List accounts in one wallet, one page at a time
- [`tk wallet account create`](#tk-wallet-account-create): Create accounts from a `CreateWalletAccountsIntent` parameters object

##### `tk wallet account list`

List accounts in one wallet, one page at a time

```
tk wallet account list [OPTIONS] --wallet-id <WALLET_ID>
```

| Argument | Notes | Description |
|---|---|---|
| `--wallet-id <WALLET_ID>` | required | Wallet holding the accounts |
| `--limit <LIMIT>` | default `50` | Page size |
| `--cursor <CURSOR>` |  | Wallet account ID to continue after |

##### `tk wallet account create`

Create accounts from a `CreateWalletAccountsIntent` parameters object

```
tk wallet account create [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

### `tk sign`

Sign payloads and serialized transactions

```
tk sign [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk sign payload`](#tk-sign-payload): Sign a payload with explicit encoding and hash function in JSON input
- [`tk sign transaction`](#tk-sign-transaction): Sign an already serialized transaction; does not broadcast

#### `tk sign payload`

Sign a payload with explicit encoding and hash function in JSON input

```
tk sign payload [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

#### `tk sign transaction`

Sign an already serialized transaction; does not broadcast

```
tk sign transaction [OPTIONS] <--input-json <INPUT_JSON>|--input-file <INPUT_FILE>>
```

| Argument | Notes | Description |
|---|---|---|
| `--input-json <INPUT_JSON>` |  | Inline JSON parameters (no activity envelope) |
| `--input-file <INPUT_FILE>` |  | Read JSON parameters from a file, or - for stdin |

Constraints:

- exactly one of `--input-json`, `--input-file`

### `tk secret`

Manage encrypted secrets

```
tk secret [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk secret list`](#tk-secret-list): List secret metadata; values are never returned
- [`tk secret import`](#tk-secret-import): Encrypt and import a new named secret
- [`tk secret env`](#tk-secret-env): Export every matching secret as dotenv lines
- [`tk secret delete`](#tk-secret-delete): Delete a secret
- [`tk secret export`](#tk-secret-export): Export a secret's value

#### `tk secret list`

List secret metadata; values are never returned

```
tk secret list [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--limit <LIMIT>` | default `50` | Page size, or the most matches to return when filtering |
| `--cursor <CURSOR>` |  | Secret ID to continue after |
| `--property <KEY=VALUE> (repeatable)` |  | Only secrets carrying this static property; every given property must match |
| `--name-prefix <NAME_PREFIX>` |  | Only secrets whose name starts with this prefix, for example hermes/ |

#### `tk secret import`

Encrypt and import a new named secret

```
tk secret import [OPTIONS] <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `<NAME>` | required | Name of the new secret |
| `--from-file <FROM_FILE>` |  | File holding the secret value |
| `--property <KEY=VALUE> (repeatable)` |  | Policy-visible property bound to the secret |

#### `tk secret env`

Export every matching secret as dotenv lines

```
tk secret env [OPTIONS] <--property <KEY=VALUE>|--name-prefix <NAME_PREFIX>>
```

| Argument | Notes | Description |
|---|---|---|
| `--property <KEY=VALUE> (repeatable)` |  | Only secrets carrying this static property; every given property must match |
| `--name-prefix <NAME_PREFIX>` |  | Only secrets whose name starts with this prefix, for example hermes/ |

Constraints:

- at least one of `--property`, `--name-prefix`

#### `tk secret delete`

Delete a secret

```
tk secret delete [OPTIONS] <--name <NAME>|--id <ID>>
```

| Argument | Notes | Description |
|---|---|---|
| `--name <NAME>` |  | Name of the secret |
| `--id <ID>` |  | ID of the secret |

Constraints:

- exactly one of `--name`, `--id`

#### `tk secret export`

Export a secret's value

```
tk secret export [OPTIONS] <--name <NAME>|--id <ID>>
```

| Argument | Notes | Description |
|---|---|---|
| `--name <NAME>` |  | Name of the secret |
| `--id <ID>` |  | ID of the secret |
| `--out <OUT>` |  | Write the value to this new file (0600) instead of stdout |
| `--context <KEY=VALUE> (repeatable)` |  | Policy-visible context for this export request only |

Constraints:

- exactly one of `--name`, `--id`

### `tk session`

Rotate short-lived credentials for agent profiles

```
tk session [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk session request`](#tk-session-request): Generate a new credential for a saved profile and print its public key for a provisioner to register
- [`tk session provision`](#tk-session-provision): Register a public key on a user as an expiring API key
- [`tk session activate`](#tk-session-activate): Switch a saved profile to its pending credential once it is registered
- [`tk session status`](#tk-session-status): Report when a saved profile's credential expires

#### `tk session request`

Generate a new credential for a saved profile and print its public key for a provisioner to register

```
tk session request [OPTIONS] --profile-name <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | required | Saved profile that will use the new credential |
| `--replace` |  | Discard an unregistered pending request and start over |

#### `tk session provision`

Register a public key on a user as an expiring API key

```
tk session provision [OPTIONS] --user-id <USER_ID> --public-key <PUBLIC_KEY>
```

| Argument | Notes | Description |
|---|---|---|
| `--user-id <USER_ID>` | required | User who will own the new expiring API key |
| `--public-key <PUBLIC_KEY>` | required | Compressed P256 public key (hex) printed by `tk session request` |
| `--expires-in <EXPIRES_IN>` | default `7d` | Lifetime of the key, for example 7d, 48h, 30m |
| `--label <LABEL>` |  | Label of the API key; defaults to `session-EXPIRES_IN-UNIX_SECONDS`, for example session-7d-1789000000 |

#### `tk session activate`

Switch a saved profile to its pending credential once it is registered

```
tk session activate [OPTIONS] --profile-name <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | required | Saved profile with a pending session request |

#### `tk session status`

Report when a saved profile's credential expires

```
tk session status [OPTIONS] --profile-name <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | required | Saved profile to inspect |
| `--warn-before <WARN_BEFORE>` | default `48h` | Fail with `session_expiring` when less than this remains |

### `tk gpg`

Sign with PGP keys backed by wallet accounts

```
tk gpg [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk gpg keys`](#tk-gpg-keys): Manage PGP keys held as wallet accounts
- [`tk gpg sign`](#tk-gpg-sign): Write an armored detached signature for a file
- [`tk gpg agent`](#tk-gpg-agent): Serve registered PGP keys over a Unix socket

#### `tk gpg keys`

Manage PGP keys held as wallet accounts

```
tk gpg keys [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk gpg keys create`](#tk-gpg-keys-create): Create a PGP signing key for a user ID as wallet accounts and register it
- [`tk gpg keys add`](#tk-gpg-keys-add): Register an existing PGP key from a wallet
- [`tk gpg keys remove`](#tk-gpg-keys-remove): Forget a registered key
- [`tk gpg keys list`](#tk-gpg-keys-list): List the registered keys
- [`tk gpg keys export`](#tk-gpg-keys-export): Print the armored public key block of a registered key

##### `tk gpg keys create`

Create a PGP signing key for a user ID as wallet accounts and register it

```
tk gpg keys create [OPTIONS] --wallet-id <WALLET_ID> --user-id <USER_ID>
```

| Argument | Notes | Description |
|---|---|---|
| `--wallet-id <WALLET_ID>` | required | Wallet to create the accounts in |
| `--user-id <USER_ID>` | required | The PGP user ID, for example "Ada Lovelace <ada@example.com>" |

##### `tk gpg keys add`

Register an existing PGP key from a wallet

```
tk gpg keys add [OPTIONS] --wallet-id <WALLET_ID>
```

| Argument | Notes | Description |
|---|---|---|
| `--wallet-id <WALLET_ID>` | required | Wallet holding the key |
| `--key <KEY>` |  | Fingerprint or long key ID of the key |

##### `tk gpg keys remove`

Forget a registered key

```
tk gpg keys remove [OPTIONS] <KEY>
```

| Argument | Notes | Description |
|---|---|---|
| `<KEY>` | required | Fingerprint or long key ID of the key |

##### `tk gpg keys list`

List the registered keys

```
tk gpg keys list [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--wallet-id <WALLET_ID>` |  | List the PGP keys in this wallet instead of the registered keys |

##### `tk gpg keys export`

Print the armored public key block of a registered key

```
tk gpg keys export [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--key <KEY>` |  | Fingerprint or long key ID of the key |

#### `tk gpg sign`

Write an armored detached signature for a file

```
tk gpg sign [OPTIONS] [FILE]
```

| Argument | Notes | Description |
|---|---|---|
| `--key <KEY>` |  | Fingerprint or long key ID of the key |
| `<FILE>` |  | File to sign; with no file, tk reads stdin |
| `--output <OUTPUT>` |  | Write the armored signature here instead of stdout |

#### `tk gpg agent`

Serve registered PGP keys over a Unix socket

```
tk gpg agent [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk gpg agent serve`](#tk-gpg-agent-serve): Run the agent in the foreground

##### `tk gpg agent serve`

Run the agent in the foreground

```
tk gpg agent serve [OPTIONS] --key <KEY>
```

| Argument | Notes | Description |
|---|---|---|
| `--key <KEY>` | required | Serve only this registered key |
| `--socket <PATH>` |  | Unix socket path to bind for PGP signing requests |
| `--socket-mode <SOCKET_MODE>` | default `600` | Octal permissions for the socket |

### `tk skills`

Serve the embedded turnkey-tk agent skills

```
tk skills [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk skills list`](#tk-skills-list): List the embedded skills with their descriptions
- [`tk skills show`](#tk-skills-show): Print one embedded skill as Markdown
- [`tk skills install`](#tk-skills-install): Install the turnkey-tk package as DIR/turnkey-tk; an existing destination is never replaced, the same package is a no-op, and any other content is refused with `invalid_input`

#### `tk skills list`

List the embedded skills with their descriptions

```
tk skills list [OPTIONS]
```

#### `tk skills show`

Print one embedded skill as Markdown

```
tk skills show [OPTIONS] --name <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `--name <NAME>` | required | A skill name from `tk skills list`, or `references/NAME` for a reference |

#### `tk skills install`

Install the turnkey-tk package as DIR/turnkey-tk; an existing destination is never replaced, the same package is a no-op, and any other content is refused with `invalid_input`

```
tk skills install [OPTIONS] --into <DIR>
```

| Argument | Notes | Description |
|---|---|---|
| `--into <DIR>` | required | Directory that receives the `turnkey-tk` package; created when missing |

### `tk login`

Verify a saved profile with Turnkey and select it

```
tk login [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | default `default` | Saved profile to verify and select |

### `tk whoami`

Verify the selected identity with Turnkey

```
tk whoami [OPTIONS]
```

### `tk auth`

Manage API authentication

```
tk auth [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk auth login`](#tk-auth-login): Verify a saved profile with Turnkey and select it
- [`tk auth status`](#tk-auth-status): Inspect local credential readiness without contacting the server
- [`tk auth whoami`](#tk-auth-whoami): Verify the selected identity with Turnkey
- [`tk auth logout`](#tk-auth-logout): Clear the saved profile selection

#### `tk auth login`

Verify a saved profile with Turnkey and select it

```
tk auth login [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | default `default` | Saved profile to verify and select |

#### `tk auth status`

Inspect local credential readiness without contacting the server

```
tk auth status [OPTIONS]
```

#### `tk auth whoami`

Verify the selected identity with Turnkey

```
tk auth whoami [OPTIONS]
```

#### `tk auth logout`

Clear the saved profile selection

```
tk auth logout [OPTIONS]
```

### `tk profile`

Manage named API identities

```
tk profile [OPTIONS] <COMMAND>
```

Subcommands:

- [`tk profile create`](#tk-profile-create): Save a new profile without contacting Turnkey
- [`tk profile list`](#tk-profile-list): List saved profiles and the active selection
- [`tk profile show`](#tk-profile-show): Show one saved profile
- [`tk profile use`](#tk-profile-use): Select a saved profile after checking its credential file
- [`tk profile delete`](#tk-profile-delete): Remove a saved profile
- [`tk profile set`](#tk-profile-set): Update a saved profile

#### `tk profile create`

Save a new profile without contacting Turnkey

```
tk profile create [OPTIONS]
```

| Argument | Notes | Description |
|---|---|---|
| `--profile-name <NAME>` | default `default` | Name for the new profile |
| `--api-key-file <API_KEY_FILE>` |  | Existing P256 credential JSON file to use; without it, a fresh credential is written under ~/.config/turnkey/tk/api-keys/ |

#### `tk profile list`

List saved profiles and the active selection

```
tk profile list [OPTIONS]
```

#### `tk profile show`

Show one saved profile

```
tk profile show [OPTIONS] <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `<NAME>` | required | Saved profile to show |

#### `tk profile use`

Select a saved profile after checking its credential file

```
tk profile use [OPTIONS] <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `<NAME>` | required | Saved profile to select |

#### `tk profile delete`

Remove a saved profile

```
tk profile delete [OPTIONS] <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `<NAME>` | required | Saved profile to remove |

#### `tk profile set`

Update a saved profile

```
tk profile set [OPTIONS] <NAME>
```

| Argument | Notes | Description |
|---|---|---|
| `<NAME>` | required | Saved profile to update |
| `--api-key-file <API_KEY_FILE>` |  | Existing P256 credential JSON file to use from now on |