ProxKey CLI

ProxKey CLI is the command-line interface for sending support issues, CI failures, QA notes, logs, and incident context to the ProxKey backend for automated engineering triage.

It is built for engineering teams that want a consistent way to submit raw operational context from local machines, internal workflows, and CI/CD pipelines. ProxKey CLI supports interactive login, API key authentication, backend configuration, report export, and automation-friendly analysis commands.

What It Does

With ProxKey CLI, you can:

• connect to a ProxKey backend
• authenticate as a user or service account
• submit logs and issue context for triage
• analyze CI and incident-related files
• export generated reports in portable formats
• manage API keys for bots, CI agents, and internal tooling

Typical use cases include:

• sending a failed build log to ProxKey from a local machine
• attaching incident notes to a triage request
• analyzing CI output in a GitHub Actions or other pipeline job
• exporting triage output as Markdown for tickets, docs, or follow-up communication
• creating scoped API keys for automation

Install

Install globally with npm:

npm install -g @notomer/proxkey-cli

You can also install it with other package managers:

pnpm add -g @notomer/proxkey-cli
yarn global add @notomer/proxkey-cli
bun add -g @notomer/proxkey-cli

After installation, verify the CLI is available:

proxkey version

You can also inspect the available commands at any time:

proxkey help

Quick Start

A typical setup flow looks like this:

1. Point the CLI at your backend

Set the backend URL once:

proxkey config set api-base-url https://api.proxkey.dev

This stores your configuration in:

~/.proxkey/auth.json

You usually only need to do this once per machine or environment.

2. Authenticate

For interactive use:

proxkey login

For headless environments such as CI:

proxkey auth set-key pk_live_your_key_here

3. Confirm your session

proxkey whoami
proxkey status

4. Submit a file for triage or analysis

proxkey triage --file ./logs/build.log

Or:

proxkey ci analyze --file ./logs/incident.txt --json

Backend Configuration

The CLI can be pointed at any compatible ProxKey backend.

Set a default backend URL:

proxkey config set api-base-url https://api.proxkey.dev

That setting is persisted locally and reused for future commands.

You can also override the backend URL for an individual command:

proxkey login --api-base-url https://api.proxkey.dev

This is useful when:

• testing against staging or local environments
• switching between production and development backends
• running commands in temporary or isolated automation workflows

Authentication

ProxKey CLI supports both interactive login and API key-based authentication.

Interactive Login

For local developer use, run:

proxkey login

If the backend exposes Auth0 device login through GET /api/auth/config, proxkey login will automatically use that flow.

API Key Authentication

For CI, bots, or other non-interactive environments:

proxkey auth set-key pk_live_your_key_here

This lets your automation submit packets and run analysis commands without requiring an interactive session.

Check Identity And Auth State

To inspect the current session:

proxkey whoami
proxkey status

These commands are useful for troubleshooting local auth problems and confirming which user or key is active.

Common Commands

Below are some common commands you would want users to discover quickly.

General

proxkey help
proxkey version
proxkey status
proxkey whoami

Triage And Analysis

proxkey triage --file ./logs/build.log
proxkey ci analyze --file ./logs/incident.txt --json

Exporting Reports

proxkey export --format markdown <report-id>

API Key Management

proxkey auth create-key ci-bot --scope packets:write --scope packets:read
proxkey auth list-keys
proxkey auth revoke-key <api-key-id>

Example Workflows

Analyze A Failed Build Log Locally

proxkey triage --file ./logs/build.log

Use this when a local build, test run, or script has failed and you want ProxKey to process the raw output.

Analyze CI Output In JSON Format

proxkey ci analyze --file ./logs/incident.txt --json

This is useful for automation, structured downstream processing, or piping results into another internal tool.

Export A Report To Markdown

proxkey export --format markdown <report-id>

This is useful when you want to:

• paste the output into an issue tracker
• attach it to an incident document
• share triage findings with teammates
• store analysis results in internal documentation

Create A Dedicated CI Key

proxkey auth create-key ci-bot --scope packets:write --scope packets:read

This lets you issue narrowly scoped credentials for automation instead of reusing personal auth.

Environment Variables

The CLI also supports environment-variable based overrides.

PROXKEY_API_BASE_URL

Overrides the configured backend URL.

Example:

export PROXKEY_API_BASE_URL=https://api.proxkey.dev

This is helpful in CI or ephemeral environments where you do not want to persist configuration to disk.

PROXKEY_API_KEY

Overrides the stored auth token or API key.

Example:

export PROXKEY_API_KEY=pk_live_your_key_here

This is especially useful for:

• GitHub Actions
• CI/CD runners
• containerized workflows
• temporary test environments

Configuration Storage

By default, the CLI stores persistent configuration in:

~/.proxkey/auth.json

This may include backend connection configuration and local authentication state, depending on how the CLI is used.

For shared systems or CI runners, environment variables are generally the safer option.

Homebrew Release Flow

If you want to distribute the CLI through Homebrew, generate a formula from the npm package tarball:

node scripts/generate-homebrew-formula.mjs

This writes:

packaging/homebrew/proxkey.rb

Recommended flow:

1. publish the npm package
2. generate the formula
3. copy the generated formula into your Homebrew tap
4. publish or update the tap