OX CLI

OX CLI tool allows developers to scan modified files in their local repositories for security issues. It works similarly to the IDE extension, but is designed for command-line usage.

Currently the following issue categories are supported: Open Source Security, Code Security, SBOM, IaC, Secret/PII.

The repository you scan must exist in your organization and be known to OX.

In case the repository is not recognized, scans will fail.

Prerequisites

Before you begin the installation process, make sure the following tools are installed:

• Node.js, version 16 and newer
• npm
• Git

Installing OX CLI

The CLI installation method is for users installing from the public npm registry.

To install OX CLI:

npm install -g @oxappsec/ox-cli

Verifying package integrity

Each release publishes a checksums.txt containing the SHA-256 hash of bundle.js. You can verify the installed binary matches the published hash:

# Download checksums.txt for the installed version
VERSION=$(ox-cli --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
TMP=$(mktemp)
curl -fsSL "https://registry.npmjs.org/@oxappsec/ox-cli/-/ox-cli-${VERSION}.tgz" -o "$TMP"
tar -xzOf "$TMP" package/checksums.txt
rm "$TMP"

# Compute the hash of the installed bundle
BUNDLE=$(npm root -g)/@oxappsec/ox-cli/bundle.js
sha256sum "$BUNDLE"          # Linux
# shasum -a 256 "$BUNDLE"   # macOS

The hash printed by sha256sum must match the value in checksums.txt.

Verifying successful installation

To verify that the CLI is working, run ox-cli --version. The available commands, options, and the current version appear.

Updating OX CLI

To update OX CLI in GA distribution, update public NPM builds:

• Run:

ox-cli update

To verify the update in both distributions:

ox-cli --version

Uninstalling OX CLI

To uninstall OX CLI, run:

npm uninstall -g @oxappsec/ox-cli

Before you begin running scans in OX CLI

Before you start scanning, you need to perform the initial configuration, which includes configuring the OX CLI tool with the necessary credentials.

To perform the initial configuration:

1. Retrieve your IDE/CLI integration key from the OX platform.
2. In OX CLI, run:

ox-cli config set api-key <your-api-key>

You can also run ox-cli config with no parameters and press 'Enter' to be prompted for the API key interactively.

3. (Optional) Set API endpoint for staging or development environments:

ox-cli config set api-host https://custom.api.endpoint.com

4. (Optional) Enable telemetry.

ox-cli config set enable-telemetry true

5. Use environment variables as an alternative to config:

   export OX_API_KEY=your-api-key
   export OX_API_ENDPOINT=https://your-api-endpoint.com
   ox-cli scan

   Recommended: Run ox-cli config without arguments to securely enter your API key.

6. To confirm your current configuration:

ox-cli config get <parameter>

Authenticating with OAuth

As an alternative to an API key, OX CLI supports browser-based OAuth login. After enabling OAuth mode, ox-cli login opens your default browser, completes the OAuth handshake, and securely stores the resulting tokens for subsequent commands.

To authenticate with OAuth:

1. Make sure your API endpoint is configured (OAuth uses it to discover the OAuth server):

ox-cli config set api-host https://api.cloud.ox.security

2. Switch the CLI to OAuth mode by setting the API key value to oauth:

ox-cli config set api-key oauth

This clears any previously stored OAuth tokens and tells the CLI to authenticate through OAuth instead of a static API key.

3. Start the OAuth login flow:

ox-cli login

Your browser opens automatically. After you sign in, the CLI receives the tokens and confirms with ✅ Login successful!. Tokens are persisted, so you only need to log in again when they expire or after ox-cli logout.

4. To sign out and clear stored OAuth tokens:

ox-cli logout

Optional environment variables for OAuth:

| Variable | Description | | -------------------- | ---------------------------------------------------------------------------------------- | | OX_OAUTH_URL | Override the OAuth server URL (useful for staging or development environments). | | OX_OAUTH_CLIENT_ID | Override the OAuth client ID used by the CLI. | | OX_API_ENDPOINT | Required when using OAuth — the CLI derives the default OAuth server from this endpoint. |

To switch back to API-key auth, run ox-cli config set api-key <your-api-key> with your real key.

Authenticating with VibeSec (per-scan)

If you already have an IDE agent (Claude Code, Cursor, or VS Code Copilot) configured with OX Security, you can run a single scan using its stored token without changing your CLI configuration. This is a per-scan override — the next ox-cli scan invocation reverts to your configured API key or OAuth.

To run a scan with the VibeSec token:

ox-cli scan --use-vibesec-auth

The CLI automatically detects the credentials stored by a supported IDE agent (Claude Code, Cursor, or VS Code Copilot), checking them in that order and using the first valid token it finds. The detected token (API key or OAuth) and its associated API endpoint are applied to that single scan — your saved CLI configuration is left untouched.

Note: The token is written by the OX IDE extension when VibeSec support is active. If no token is found, the scan fails with a missing-auth error.

Scanning modified files in OX CLI

During the scan process, OX CLI detects changes in the repository, such as new lines, changed dependencies, deleted files and so on using the scan [targetDir] command.

It compresses only those changes and then sends them securely to the backend for analysis.

Important: Only local modifications are scanned, not the entire repository. The scanned repository must already exist in your OX organization.

OX CLI scans a repository for security issues. If targetDir is not provided, the current directory is scanned.

Usage:

ox-cli scan [targetDir] [options]

Arguments:

• targetDir Directory to scan (defaults to the current directory)

Options:

| Option | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --format <format> | Set the output format. Supported values: text (default), json, sarif. | | --severity <severities> | Filter results by severity. Provide a comma-separated list, e.g., Critical,High.Supported severities: Critical, High, Medium, Low, Info. Default: when this option is omitted, only Critical, High, and Medium issues are shown — Low and Info issues are hidden. To include them, list them explicitly, e.g., --severity Critical,High,Medium,Low,Info.The Appoxalypse severity level issues are always presented by default and you cannot set the CLI not to display them. | | --group <group> | OX CLI allows the same grouping options, as OX IDE extension.Group results in the report. Supported values: severity (default), category. | | --git-remote-name <remote> | Specify the Git remote name. | | --use-vibesec-auth | Use the VibeSec token written by a configured IDE agent (Claude Code, Cursor, or Copilot) for this scan only. Overrides the configured API key / OAuth without changing it. | | --full-scan | Scan all files in the target directory instead of only git-changed files. See Full scan for details. | | --category <categories> | Restrict the scan to one or more security categories. Provide a comma-separated list, e.g., oss,secrets.Supported categories: oss (Open Source Security), code (Code Security), sbom (SBOM), iac (Infrastructure as Code), secrets (Secret/PII). |

Note: When --category is omitted, all categories are scanned. Example: ox-cli scan --category oss,secrets scans Open Source Security and Secret/PII only.

Example command:

ox-cli scan ./my-project --severity Critical,High --format json

Example output:

Specifying Git remote

You can compare your local changes against a specific Git remote, which helps determining what is new or modified compared to the remote repository.

To compare your local changes against a specific Git remote:

• Replace origin with the name of your Git remote and run:

ox-cli scan --git-remote-name origin

Full scan

By default, ox-cli scan only packages and sends the files that have changed locally relative to the remote (git diff mode). The --full-scan flag changes this behaviour: the entire target directory is packaged and sent to OX for analysis, regardless of what has or has not changed.

When to use full scan:

• You want to audit a codebase that has no uncommitted changes (e.g. after a fresh git clone).
• You are scanning a directory that is not a git repository.
• You want comprehensive coverage of every file, not just recent modifications.

Note: The scan availability pre-check (which verifies the repository is registered in your OX organization) is skipped for full scans. Results are still associated with the repository derived from the git remote when one is available.

Size limit: If the uncompressed size of all collected files exceeds the allowed cap, the scan will fail with an error asking you to run on a smaller subdirectory. In that case, pass a more specific targetDir to narrow the scope.

To run a full scan:

ox-cli scan --full-scan

To run a full scan on a specific directory:

ox-cli scan ./my-project --full-scan

To combine with other options:

ox-cli scan ./my-project --full-scan --severity Critical,High --format sarif

To run a full scan restricted to specific categories:

ox-cli scan ./my-project --full-scan --category oss,secrets

Restricting scans by category

By default every scan covers all supported security categories. Use the --category flag with a comma-separated list to tell OX to analyse only the categories you care about. It works with both regular and full scans.

| Value | Category scanned | | --------- | ----------------------------- | | oss | Open Source Security | | code | Code Security | | sbom | SBOM | | iac | Infrastructure as Code | | secrets | Secret/PII |

Examples:

# Scan only for secrets and IaC issues in changed files
ox-cli scan --category secrets,iac

# Full scan for OSS vulnerabilities only
ox-cli scan --full-scan --category oss

# Code security and secrets, critical/high only, JSON output
ox-cli scan --category code,secrets --severity Critical,High --format json

Tip: You can also set the category filter via the OX_CATEGORY environment variable (e.g. OX_CATEGORY=oss,secrets), which is convenient in CI. An explicit --category flag takes precedence over it.

Git Hook Integration

OX CLI can be integrated with Git hooks to block risky code before commit or push.

Per-repository hooks

These install into the current repository's .git/hooks directory.

1. To install the pre-push hook (default):

ox-cli install-git-hook --type pre-push

2. To install the pre-commit hook:

ox-cli install-git-hook --type pre-commit

3. To uninstall the pre-push hook:

ox-cli uninstall-git-hook --type pre-push

4. To overwrite an existing (non-OX) hook, add --force.

Machine-wide (global) hooks

Install the hook once for all of your repositories instead of running install-git-hook in each one. This uses Git's global core.hooksPath configuration.

1. To install a global hook:

ox-cli install-git-hook --global --type pre-push
ox-cli install-git-hook --global --type pre-commit

2. To uninstall a global hook:

ox-cli uninstall-git-hook --global --type pre-push

Notes:

• With --global, any positional target directory is ignored, and --force has no effect.
• If you already use a global hooks directory, OX installs alongside your existing hooks: your current hook is preserved and chained — it runs first, then the OX scan. Any per-repository .git/hooks hook is also still run.

Limitations

• Repositories that set their own core.hooksPath are not covered. Git gives a repository-local core.hooksPath precedence over the global one, so in those repos the global OX hook does not run at all. This is common with hook managers such as Husky, lefthook, and pre-commit. For such a repository, install a per-repository hook instead (ox-cli install-git-hook inside it), or add the OX scan to that repository's existing hook manager.
• POSIX shell required. The global hook is a /bin/sh script (it relies on mktemp, grep, etc.). On Windows it runs under Git's bundled shell.
• If a repository's hooks directory already contains an OX backup from a previous run, install-git-hook --global will ask you to run uninstall-git-hook --global first; uninstalling preserves any existing hooks by archiving them rather than deleting them.

For further support, contact your OX Security representative.