Impri CLI

Status — v0.1, pre-release. The CLI lives at cli/ in this repository and is not yet published to npm. Install it from the local source using the build steps below. The REST API it wraps is stable and works against either the hosted cloud (api.impri.dev, early beta) or a self-hosted instance — see impri init --cloud --signup below.

The impri CLI is the fastest way to manage the approval inbox from a terminal — push actions, watch for new ones, approve or reject, and manage watchers and API keys — without writing any code.

Install (local, pre-npm)

The CLI depends on the TypeScript SDK via a file: reference. Build the SDK first:

cd sdk/typescript && npm install && npm run build
cd ../cli && npm install && npm run build

Install globally to put impri on your PATH:

npm install -g ./cli
impri --version

The build inlines the SDK into a single dist/cli.js (shebang included). A global install requires no node_modules/ at runtime — only Node 18+.

Dev mode (no build step, for iterating on the CLI source):

cd cli && npx tsx src/cli.ts inbox

Onboarding

Run impri init once to store your base URL and API key:

# Self-hosted (default)
impri init

# Cloud — connect with an existing key
impri init --cloud

# Cloud — create a new free project and key in one step
impri init --cloud --signup

# Seed two sample actions so the inbox is not empty on first run
impri init --cloud --signup --demo

init calls GET /v1/project to validate the key, then writes ~/.impri/config.json (mode 0600). The interactive flow:

1. Prompt for base URL (default: http://localhost:8484).
2. Prompt for API key (im_...) with masked input.
3. Validate the key against the server.
4. Write the config file.
5. Print the connected project name.

With --cloud --signup, the CLI calls POST /v1/signup, prints the returned im_... key once inside a box border with a "store this now" warning, pauses for confirmation, then saves.

Config and credentials

File: ~/.impri/config.json Directory created as 0700; file written as 0600 on every save.

{
  "base_url": "https://api.impri.dev",
  "api_key": "im_xxxxxxxxxxxxxxxxxxxxxxxx"
}

Precedence (highest wins):

Environment variables take effect immediately without touching the config file — suitable for CI, Docker, and per-process overrides:

IMPRI_BASE_URL=http://staging.internal:8484 \
IMPRI_API_KEY=im_stg_... \
impri inbox

Security notes:

• The key is never logged, never printed back in full, and never echoed during interactive input (masked with *).
• Any --verbose or debug output redacts the key to its prefix only: im_XXXX****.
• A missing config file produces a friendly error, not a stack trace.

Commands

impri init

impri init [--base-url <url>] [--cloud] [--signup] [--demo]

Interactive onboarding. Prompts for base URL and API key, validates credentials, and writes ~/.impri/config.json.

To supply the API key non-interactively, pipe it on stdin or set the IMPRI_API_KEY environment variable. The env var takes precedence over the prompt.

impri login

impri login [--base-url <url>] [--cloud]

Alias for impri init. Re-run onboarding to rotate your key or switch between self-hosted and cloud without wiping other settings. Supply the key via the interactive prompt, piped stdin, or IMPRI_API_KEY env var.

impri status

impri status [--json]

Verify the active config by calling GET /healthz and GET /v1/project. Prints:

• Connected project name
• Base URL
• Key prefix (im_xxxx****)
• Current pending action count

Exits 1 if the server is unreachable or the key is invalid.

Approval Inbox

impri push

impri push --kind <kind> --title <title> [options]

Create an action for human approval (POST /v1/actions). Preview body is read from --body or stdin when omitted, enabling pipe usage.

Examples:

# Push a draft email for review
impri push --kind email.send \
  --title "Draft: Q3 newsletter" \
  --body "Hi everyone, ..." \
  --format markdown \
  --editable preview.body

# Read preview from stdin
echo "$QUERY" | impri push --kind db.exec --title "Run migration"

# Push and block until the human decides
impri push --kind reddit.comment \
  --title "Reply: self-hosting AI" \
  --body "$(cat reply.md)" \
  --wait --timeout 600

impri inbox

impri inbox [--kind <kind>] [--limit <n>] [--json]

Show only pending actions — shorthand for impri list --status pending. This is the primary human operator view.

impri inbox
impri inbox --kind email.send

impri list

impri list [--status <pending|approved|rejected|expired>] [--kind <kind>] \
           [--since <iso-date>] [--q <search>] [--limit <n>] [--json]

List actions newest-first in a tabular view (id, kind, title, status, age). Defaults to all statuses.

impri list --status approved --since 2026-07-01
impri list --q "migration" --json | jq .id

impri get <action-id>

impri get <action-id> [--json]

Fetch a single action and print full detail: status, preview, editable fields, expires_at, and the decision (including final_preview and diff) when already decided.

impri get act_abc123

impri approve <action-id>

impri approve <action-id> [--edit <new-body-text>] [--json]

Approve an action (POST /v1/actions/:id/decision, verdict=approve).

--edit replaces the preview body before approving. The CLI fetches the action first and exits with an error if preview.body is not in the action's editable list.

impri approve act_abc123

# Approve with an edited body
impri approve act_abc123 --edit "$(cat edited-reply.md)"

Exits 0 on success.

impri reject <action-id>

impri reject <action-id> [--json]

Reject an action (POST /v1/actions/:id/decision, verdict=reject). Prints the DecisionResult.

Exits 0 on success; exits 2 on ImpriConflict (already decided).

impri tail

impri tail [--kind <kind>] [--interval <seconds>] [--json]

Long-running watch mode for the human operator. Polls GET /v1/actions?status=pending every --interval seconds (default: 10, minimum: 5 to stay under rate limits) and prints newly-arrived pending actions as they appear. Tracks the latest created_at seen to avoid reprinting.

Press Ctrl-C to exit.

# Terminal 1 — tail the inbox
impri tail

# Terminal 2 — decide on actions printed by tail
impri approve act_xyz789

With --json, each new action is streamed as a JSON line — useful for piping into other tools.

Watchers

impri presets

impri presets [--category <Community|Developer|Content|Research|News|Monitoring>] [--json]

List the 18 watcher preset templates (GET /v1/watcher-presets) in a grouped table showing preset ID, description, required params, and default schedule. Use the preset ID with impri watch add.

impri presets
impri presets --category Developer

Available presets:

impri watch add <preset-id>

impri watch add <preset-id> [--param key=value]... [--name <name>] [--schedule <every>] [--json]

Create a watcher from a named preset (POST /v1/watchers/from-preset). --param is repeatable.

# GitHub releases for fastify/fastify, polled hourly
impri watch add github-releases \
  --param owner=fastify \
  --param repo=fastify \
  --schedule 1h

# Reddit keyword search with a custom name
impri watch add reddit-keyword \
  --param "query=self-hosting AI" \
  --param subreddit=selfhosted \
  --name "SH AI mentions"

# Hacker News front page (no params required)
impri watch add hn-front-page

Prints the created watcher ID and next_run_at on success.

impri watchers list

impri watchers list [--status <active|paused|degraded>] [--kind <rss|reddit_search|url_diff>] [--json]

List all watchers with status, kind, schedule, fail_count, and next_run_at.

impri watchers get <watcher-id>

impri watchers get <watcher-id> [--json]

Fetch a single watcher by ID, including item_count (total deduplicated items seen since creation).

impri watchers delete <watcher-id>

impri watchers delete <watcher-id> [--yes]

Permanently delete a watcher and its deduplication history. Pending inbox actions created by this watcher are not deleted.

--yes skips the interactive confirmation prompt — safe for scripting.

API Keys

All key commands require admin scope.

impri keys list

impri keys list [--json]

List all API keys: prefix, scopes, created_at, last_used_at, and revocation status. Raw key values are never returned by the server after creation.

impri keys create

impri keys create --name <name> --scopes <actions|watch|admin>[,...]

Create a new API key (POST /v1/keys) and print the raw im_... value exactly once. The CLI displays the key prominently and warns it will not be shown again.

# Per-agent key with minimal scope
impri keys create --name "deploy-agent" --scopes actions

# Ops bot that can also manage watchers
impri keys create --name "ops-bot" --scopes actions,watch

impri keys revoke <key-id>

impri keys revoke <key-id> [--yes]

Revoke a key permanently (DELETE /v1/keys/:id). All subsequent requests with that key will be rejected with 401.

--yes skips the confirmation prompt.

Human operator workflow

The typical setup for monitoring an active agent:

# Terminal 1 — watch for new pending actions
impri tail

# Terminal 2 — inspect and decide on a specific action
impri get act_abc123
impri approve act_abc123
# or
impri reject act_abc123

For a lighter setup, poll the inbox on a loop:

watch -n 30 impri inbox

Inspect then edit a draft before approving:

impri get act_abc123         # read the preview
$EDITOR /tmp/reply.md        # edit locally
impri approve act_abc123 --edit "$(cat /tmp/reply.md)"

Exit codes

Build reference

cli/
  src/cli.ts          Entry point — subcommands registered with commander
  package.json        name: @impri/cli, version: 0.1.0, bin: { impri: ./dist/cli.js }
  tsup.config.ts      Bundles SDK inline via noExternal: [/@impri/]; shebang injected
  dist/cli.js         Compiled output (generated by npm run build)

Build sequence for a clean checkout:

cd sdk/typescript && npm install && npm run build
cd ../cli && npm install && npm run build
npm install -g ./cli

The bundle carries the shebang so the OS can execute dist/cli.js directly. No node_modules/ needed at runtime beyond Node 18.

See also:

• TypeScript SDK reference — for agents that push and poll programmatically
• Quickstart — zero to first approved action in < 5 min
• Watcher presets — full preset catalog with param reference
• Inbox UX — keyboard shortcuts, bulk approve/reject, filters (web inbox)