Install and configure

Install the operator command

Open Account → API keys, create a key, and use the CLI installation instructions in the key-ready dialog. Select your workstation platform and copy the generated installation command. It downloads the deployment's executable and checks its checksum; it does not enroll or start a sensor. The API keys guide explains personal and team ownership, permissions, rotation, and the other credential types.

The generated installer places the command in ~/.local/bin on macOS/Linux, or %LOCALAPPDATA%/PacketSafari/bin on Windows. If a new terminal cannot find it, ensure that directory is on your PATH.

packetsafari --help

If you are also inside a PacketSafari source checkout, verify which executable the shell will run:

command -v packetsafari
packetsafari help investigate

./packetsafari in the repository is the developer launcher. Use the installed packetsafari command without ./ for PCAP submissions.

Create and save a key

Create a personal key in Account → API keys, or a team key through your team's API-key settings if you are a team administrator. Grant the capture upload/read and investigation permissions needed by your workflow. Copy the key when it is displayed; it cannot be revealed again after the dialog closes.

Use your deployment's URL. This example is for local development:

packetsafari config set server http://127.0.0.1:8080
packetsafari config set api-key 'PASTE_YOUR_API_KEY_HERE'
packetsafari config show

The saved key is redacted by config show. The configuration file contains the actual key, so keep it private. A key pasted into a shell command can also remain in shell history. API-key authentication needs no separate CLI login. Probe enrollment credentials are for sensors, not investigation submissions; see Capture probes.

Choose model defaults

Team and on-prem administrators should first follow AI provider onboarding to configure the connection, grant access, and validate the model. CLI credentials do not create an AI-provider connection.

Use a model supported by your configured AI connection. For inexpensive test runs on a connection offering Luna:

packetsafari config set model gpt-5.6-luna
packetsafari config set reasoning-effort low
packetsafari config set format markdown

Choose the AI connection with --tui, or save its actual source ID:

packetsafari config set ai-auth-source-id 'YOUR_AI_CONNECTION_ID'

Source IDs are deployment-specific; do not copy another account's ID. To use account/deployment model defaults again:

packetsafari config unset model
packetsafari config unset reasoning-effort

Environment variables and precedence

For flat CLI defaults, explicit command flags override environment variables, which override saved configuration. If a value remains omitted, the server resolves applicable account/deployment defaults and eligibility.

export PACKETSAFARI_MODEL=gpt-5.6-luna
export PACKETSAFARI_REASONING_EFFORT=low
packetsafari config show

config show displays saved values, not a resolved view of every environment or per-command override. By default, settings are stored in ~/.config/packetsafari/config.json. Use --config FILE or PACKETSAFARI_CONFIG for a different file. Login session state is separate from this configuration.

A grouped investigation file supplied with --settings FILE also supplies settings. Explicit flags override its goal, workflow and AI values; those file values currently override corresponding flat saved/environment defaults. Avoid defining the same setting in both places when you want a predictable reusable recipe.

PowerShell setup

The Windows installer places the command beneath %LOCALAPPDATA%\PacketSafari\bin. Open a new PowerShell after installation, then save defaults:

packetsafari config set server https://app.packetsafari.com
packetsafari config set api-key 'PASTE_YOUR_API_KEY_HERE'
packetsafari config set model gpt-5.6-luna
packetsafari config set reasoning-effort low
packetsafari config show

For a temporary environment-only configuration:

$env:PACKETSAFARI_BASE_URL = 'https://app.packetsafari.com'
$env:PACKETSAFARI_API_KEY = 'PASTE_YOUR_API_KEY_HERE'
packetsafari investigate "$HOME\Desktop\incident\capture.pcap" --goal security --format json
Remove-Item Env:PACKETSAFARI_API_KEY

Next: run an investigation.

Readable provider names and automatic selection

Use a connection's name instead of its internal ID:

packetsafari investigate "$HOME/Desktop/incident/capture.pcap" --goal security --provider "Team OpenRouter" --model nvidia/nemotron-3-super-120b-a12b --reasoning-effort medium --format json
packetsafari config set provider "Team OpenRouter"

--provider accepts an exact connection name (case-insensitive) or a scoped alias such as Team OpenRouter. An alias must identify exactly one permitted connection. Duplicate matches require a unique name or selection with --tui; the CLI does not choose the first account. PACKETSAFARI_PROVIDER supplies the same saved-setting override as other CLI environment variables.

When a model is supplied without an explicit --provider or --ai-auth-source-id, the CLI keeps the saved connection if it supports the model. Otherwise, it automatically selects the only permitted connection advertising that model. Multiple matches require an explicit choice. The selected connection is shown in progress output; saved configuration is not modified. This can use a different provider/billing account from an incompatible saved default. Use an explicit provider when a run must stay on a particular connection.

An explicit --provider overrides a saved source ID; an explicit --ai-auth-source-id overrides a saved provider name. Supplying both flags is an error. With --tui and a requested model, the connection menu lists permitted connections advertising that model. Workflow and reasoning eligibility are still checked by the server. Raw source IDs remain supported for automation.