Command reference

The full reference for every command, flag, exit code, environment variable, and on-disk path the Soxom CLI cares about. Most users won’t need to read this top-to-bottom — start with the dedicated guides for auth, init, validate, and preview.

soxom login

Authenticate the CLI against the Soxom API and store a token locally.

Synopsis

soxom login [--keychain]

Description

Opens a browser to the dashboard’s CLI authorization page, waits for the user to confirm, receives the token back over a loopback callback, and stores it. See Authenticate the CLI for the full flow.

Flags

Flag	Description
--keychain	Store the token in the OS keychain (macOS Keychain / libsecret / Windows Credential Manager) instead of the credentials file.

Examples

soxom login
soxom login --keychain
SOXOM_API_BASE=https://api.staging.soxom.dev soxom login

Exit codes

• 0 — authenticated and stored.
• 2 — auth flow was cancelled or timed out.

---

soxom logout

Forget the locally stored credentials. Does not revoke the token server-side — use the dashboard for that.

Synopsis

soxom logout

Exit codes

• 0 — credentials removed (or none were present).

---

soxom init

Scaffold openapi.yaml, soxom.yaml, and .gitignore in the current directory.

Synopsis

soxom init [--force]

Flags

Flag	Description
--force	Overwrite existing files.

Examples

mkdir my-sdk && cd my-sdk
soxom init
soxom init --force

Exit codes

• 0 — files written.
• 1 — would have overwritten existing files; re-run with --force.
• 2 — I/O error.

---

soxom validate

Run the validator against the local project and report diagnostics.

Synopsis

soxom validate [--format human|json]

Flags

Flag	Description
--format human|json	Output format. Defaults to human.

Examples

soxom validate
soxom validate --format json | jq '.diagnostics[] | select(.severity == "error")'

Exit codes

• 0 — no error diagnostics.
• 1 — one or more error diagnostics.
• 2 — validator could not run (missing files, invalid flags, I/O error).

See Validate your config for details.

---

soxom preview

Bundle the local project, ship it to Soxom, run a preview build, and download the generated SDK.

Synopsis

soxom preview --target <language> [--out <dir>] [--org <slug>] [--project <slug>]

Flags

Flag	Description
--target <lang>	Required. One of typescript, python, java, go.
--out <dir>	Output directory. Default: ./previews/{language}/{sdk-name}-{UTC timestamp}.
--org <slug>	Organization to bill the preview to.
--project <slug>	Project slug. Defaults to inferring from soxom.yaml’s sdk.name.

Examples

soxom preview --target typescript
soxom preview --target python --out ./out
soxom preview --target java --org acme-inc --project petstore

Exit codes

• 0 — build succeeded and artifact was downloaded.
• 1 — build failed (generator error, validation error, subscription required, quota exceeded).
• 2 — CLI could not start the build (missing auth, network error, bundle size limit exceeded).

See Preview a build for the full flow and limits.

---

Environment variables

Variable	Default	Purpose
SOXOM_API_BASE	https://api.soxom.com	Base URL of the Soxom API. Set this to point at staging or self-hosted environments. Tokens are scoped to the base URL they were issued against.
SOXOM_TOKEN	(unset)	If set, the CLI uses this as the bearer token and ignores any locally stored credentials. Intended for CI — see below.
NO_COLOR	(unset)	When set to any non-empty value, suppresses ANSI color in CLI output. Honors the no-color.org convention.
SOXOM_VALIDATE_TIMEOUT_MS	30000	Maximum time soxom validate is allowed to run before bailing out. Raise this for very large specs; lower it for stricter CI guarantees.

Using SOXOM_TOKEN in CI

CI runners typically don’t have a browser available, so soxom login won’t work. Instead, mint a long-lived token from the dashboard (Settings → CLI tokens), inject it as a secret, and export it before invoking the CLI:

# GitHub Actions example
- name: Validate spec
  env:
    SOXOM_TOKEN: ${{ secrets.SOXOM_CLI_TOKEN }}
  run: soxom validate

The CLI reads SOXOM_TOKEN once at startup and uses it for every API call for the rest of the run. Tokens minted for CI carry the same scopes as ones minted interactively.

Caution

Treat SOXOM_TOKEN like any other API credential — store it in a secrets manager, never commit it, and rotate it on a regular schedule. Tokens remain valid until their 90-day lifetime elapses or you revoke them from the dashboard.

Config-file locations

The CLI stores credentials and (eventually) per-project preferences in a single directory per OS, following platform conventions:

OS	Config directory
Linux	${XDG_CONFIG_HOME:-$HOME/.config}/soxom/
macOS	$HOME/Library/Application Support/com.soxom.cli/
Windows	%APPDATA%\soxom\

Inside that directory:

File	Purpose
credentials.json	Bearer token + API base, stored with 0600 permissions on Unix.

Delete the directory to fully forget all local CLI state.

Getting help

• soxom --help for top-level help.
• soxom <command> --help for per-command help.
• Source: github.com/soxom/soxom-cli.
• File issues at github.com/soxom/soxom-cli/issues.