Documentation

1. Installation & Auth

The CLI is designed specifically for Node.js environments and can run natively on your machine or inside a CI/CD pipeline (like GitHub Actions).

# Install the CLI globally
npm install -g @custodia/cli

# Authenticate your terminal
custodia auth --key YOUR_API_KEY

You can generate your API key by signing into the Custodia dashboard at custodia.dev and navigating to the API Keys section. Keys are stored locally at ~/.custodia.

2. Running a Scan

Custodia is strictly zero-config. We intentionally stripped out complex `--ignore` flags. The CLI automatically respects your `.gitignore` rules, bypasses massive runtime directories like `node_modules` or `.git`, and strips out heavy binary artifacts natively.

# Scan the current directory
custodia scan .

# Or scan a specific path
custodia scan ./src/backend

# Scan only files changed since last commit
custodia scan --diff

# Picks up staged, unstaged, and untracked files.
# Fast enough to run before every git push.

# Scan any public repo
custodia scan --repo owner/repo

# Pin to a specific branch, tag, or SHA
custodia scan --repo owner/repo@main

# Scan a private repo with a GitHub token
custodia scan --repo owner/repo --token YOUR_GITHUB_TOKEN

3. What exactly do we check?

4. Output Artifacts

Depending on your tier, the CLI natively bridges the gap between your local environment and executive reporting by directly generating compliance artifacts formatting.

• SAFE_REPORT.mdAuto-generated natively in your project root. Commit this alongside your pull requests as proof of your security posture.
• .safescan-reports/*.jsonAn immutable, cryptographically signed JSON evidence bundle stored locally for formal auditing bodies.
• Executive Web Report (Paid)The CLI will instantly output a securely hosted URL containing a stunning web interface mapped formally to SOC 2 and NIST. Perfect for sending directly to clients.

5. Absolute Privacy

Your source code is never compromised. The scanner reads your files and processes them through Enterprise Zero-Retention APIs -- your proprietary logic is never stored permanently and is strictly prohibited from being used to train any LLM.

6. GitHub Actions

Add the workflow below to .github/workflows/custodia.yml in your repo. It automatically runs a diff scan on every push and pull request — only the changed files are analysed, so scans are fast and quota-efficient.

Add your API key as a repository secret named CUSTODIA_API_KEY under Settings → Secrets and variables → Actions — no extra auth step needed.

name: Custodia Security Scan
on:
  push:
    branches: ["main", "master"]
  pull_request:

jobs:
  custodia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # required: lets Custodia diff against base ref

      - uses: contactdavidpersonal-code/custodia-scan-action@v1
        with:
          api-key: ${{ secrets.CUSTODIA_API_KEY }}

Need Help?

If you run into an error, hit a bug, or have a question that isn't answered here, email us directly. We respond within one business day.