Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# CLI
description: Teach your coding agent the Inkbox CLI (@inkbox/cli) for shell-native workflows

---


# CLI Skill

This skill teaches your coding agent how to drive the entire Inkbox API from a shell using the `@inkbox/cli` tool. Once installed, the agent knows which commands exist, which flags they take, which require a vault key, and which are high-risk and need user confirmation before running.

[View the source →](https://github.com/inkbox-ai/inkbox/tree/main/skills/inkbox-cli)

## What your agent learns

| Feature | Operations |
|---|---|
| Auth & runtime | `--api-key` / `INKBOX_API_KEY`, `--vault-key` / `INKBOX_VAULT_KEY`, `--base-url`, `--json` for parseable output |
| Install modes | Global (`npm install -g @inkbox/cli`), one-shot (`npx @inkbox/cli <command>`), local repo dev (`npm --prefix cli run dev -- <command>`) |
| High-risk operations | Commands that send real traffic or mutate resources — `signup create`, `email send`, `phone call`, `identity delete`, `email delete`, `vault delete`, `mailbox delete`, `number release`, `filter-mode` flips, `signing-key create` |
| Agent self-signup | `inkbox signup create`, `signup verify`, `signup resend-verification`, `signup status` — with the issued API key passed back via `--api-key` or `INKBOX_API_KEY` |
| Identities | `identity list` / `get` / `create` / `delete` / `update --new-handle` / `refresh` |
| Identity-scoped secrets | `identity create-secret` / `get-secret` / `delete-secret` / `revoke-access` / `set-totp` / `remove-totp` / `totp-code` (requires vault key) |
| Email | `email send` / `list` / `get` / `search` / `unread` / `mark-read` / `delete` / `delete-thread` / `star` / `unstar` / `thread` — all identity-scoped via `-i <handle>` |
| Phone | `phone call` / `calls` / `transcripts` / `search-transcripts` — identity-scoped |
| Text messages | `text list` / `get` / `conversations` / `conversation` / `search` / `mark-read` / `mark-conversation-read` — identity-scoped |
| Vault | `vault init` / `info` / `secrets` / `get` / `create` / `delete` / `keys` / `grant-access` / `revoke-access` / `access-list`; per-type listings (`logins`, `api-keys`, `ssh-keys`, `key-pairs`) |
| Vault secret types | `login`, `api_key`, `key_pair`, `ssh_key`, `other` — with per-type flag sets (e.g. `--password`, `--key`, `--private-key`, `--data`) |
| Mailboxes (admin) | `mailbox list` / `get` / `create` / `update` (display name / webhook / filter mode) / `delete` |
| Mailbox contact rules | `mailbox rules list` / `get` / `create` / `update` / `delete` — per-mailbox and admin-wide listings |
| Phone numbers (admin) | `number list` / `get` / `provision` / `update` (incoming-call action / filter mode) / `release` |
| Number contact rules | `number rules list` / `get` / `create` / `update` / `delete` — per-number and admin-wide listings |
| Contacts | `contacts list` / `get` / `create` / `update` / `delete` / `lookup` (by email / email-contains / email-domain / phone / phone-contains) / `import <file.vcf>` / `export` / `access list` / `grant` / `revoke` |
| Notes | `notes list` / `get` / `create` / `update` / `delete` / `access list` / `grant` / `revoke` |
| Whoami, signing keys, webhooks | `inkbox whoami`, `inkbox signing-key create`, `inkbox webhook verify --payload --secret -H ...` |
| Output conventions | `--json` for stable parsing; default table/record output for human review; stderr notices on filter-mode changes |

## Install

```bash
# via skills CLI (recommended)
npx skills add inkbox-ai/inkbox/skills

# manual (Claude Code)
git clone https://github.com/inkbox-ai/inkbox
cp -r inkbox/skills/inkbox-cli ~/.claude/skills/
```

Install the CLI itself:

```bash
# global install
npm install -g @inkbox/cli

# or run without installing
npx @inkbox/cli <command>
```

## Prerequisites

- Node.js ≥ 18
- An [Inkbox](https://www.inkbox.ai) API key from the [Console](https://inkbox.ai/console/), exported as `INKBOX_API_KEY` or passed via `--api-key`
- `INKBOX_VAULT_KEY` set only when you need vault decrypt or secret-creation flows