---
name: pixee-shared
description: "Describe the global flags, output format, exit codes, error handling, and TLS trust troubleshooting used by every Pixee CLI subcommand."
license: Apache-2.0
compatibility: Requires the pixee CLI binary on PATH
metadata:
  version: 1.2.0
  openclaw:
    category: "developer-tools"
    requires:
      bins:
        - pixee
    cliHelp: "pixee --help"
---

# Pixee CLI — Shared Reference

Conventions shared by every `pixee` subcommand. Read this before using any command-group skill
(`pixee-api`, `pixee-repo`, `pixee-workflow`, `pixee-auth`).

## Installation

```bash
brew tap pixee/pixee
brew install pixee
# or grab the archive for your platform from:
#   https://github.com/pixee/pixee-cli/releases/latest

pixee --version   # prints the release version baked into the binary
```

When downloading an archive directly, verify it against the `SHA256SUMS` manifest published on the
release before extracting the binary. Download the manifest into the same directory as the archive,
then check it (`--ignore-missing` limits the check to the archives actually downloaded):

```bash
sha256sum --ignore-missing -c SHA256SUMS      # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS  # macOS
```

## Credentials at a glance

`pixee` reads an API token and server URL from environment variables (`PIXEE_TOKEN`,
`PIXEE_SERVER`) or from a config file written by `pixee auth login`. Env vars take precedence over
stored config.

When credentials are missing, invalid, or point at the wrong server, commands exit with code 2 and
a message like:

```
Authentication failed. Run `pixee auth login` to reconfigure.
```

For the *fix* — storing a token, the `--token -` stdin pattern, config file locations,
server-precedence rules, and `pixee auth status` — see `pixee-auth`.

## Global flags

- `--server <url>` — override the configured server for a single invocation.
- `--token <token>` — API token for this invocation; overrides `PIXEE_TOKEN` and the stored
  config. See `pixee-auth` for the full credential-resolution order and the `--token -` stdin
  pattern.
- `--output text|json` — choose the output format. Default is `text` (flat, line-oriented output
  suitable for `grep`/`awk`). Use `json` for machine-readable output and pipe to `jq` for
  filtering; `pixee` does not embed a jq implementation.
- `--json` — shorthand for `--output json`.
- `--insecure` — skip TLS certificate verification for the invocation (also enabled by
  `PIXEE_INSECURE_TLS=true`). Prints a warning to stderr. Last resort for connecting to a Pixee
  Enterprise Server with a privately signed certificate — see **TLS trust failures** below for the
  preferred fix.

## Exit codes

| Code | Meaning |
| ---- | ------- |
| 0    | Success |
| 1    | General error |
| 2    | Authentication failure — token missing, expired, invalid, or wrong server. Fix via `pixee-auth`. |
| 3    | Resource not found |

Scripts and agents can branch on these codes without parsing stderr.

## Token security

- Never log token values. Never commit them to source control.
- Prefer `PIXEE_TOKEN` (env var) or `pixee auth login --token -` (stdin) over passing a token as a
  flag argument; flag arguments land in shell history. See `pixee-auth` for the full stdin
  pattern.

## Error responses

The Pixee API returns errors as `application/problem+json`. With `--output text`, `pixee` renders
the problem document's `title`, `detail`, and `instance` fields in a compact, human-readable form.
With `--output json`, the raw document is passed through unchanged.

Authentication failures exit with code 2. Not-found responses exit with code 3. Other problem
responses exit with code 1.

## TLS trust failures

`pixee` verifies certificates against its bundled Mozilla CA list, not the operating system's
trust store. When the user reports that `pixee` cannot reach an internal or enterprise Pixee
Server and the generic "Connection to ... failed" message looks like it might be a certificate
problem, read [`references/tls-troubleshooting.md`](./references/tls-troubleshooting.md). It
covers: confirming with `curl` that it's a trust failure (not DNS or a wrong URL), the preferred
fix (`NODE_EXTRA_CA_CERTS` pointing at the internal CA PEM), and `--insecure` as a last resort
with the security tradeoff to surface to the user.