pixee 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
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):
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; overridesPIXEE_TOKENand the stored config. Seepixee-authfor the full credential-resolution order and the--token -stdin pattern.--output text|json— choose the output format. Default istext(flat, line-oriented output suitable forgrep/awk). Usejsonfor machine-readable output and pipe tojqfor filtering;pixeedoes not embed a jq implementation.--json— shorthand for--output json.--insecure— skip TLS certificate verification for the invocation (also enabled byPIXEE_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.--no-pager— write straight to stdout instead of through a pager.
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) orpixee auth login --token -(stdin) over passing a token as a flag argument; flag arguments land in shell history. Seepixee-authfor 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. 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.