@trestlescan/cli

A local secret scanner for source code. Trestle finds API keys, access tokens, passwords, private keys, and certificates before you commit them by mistake, and keeps them from leaving your machine.

This is the Community edition: open source under Apache-2.0, and a mirror of the version distributed at trestlescan.com.

Install

npm install @trestlescan/cli

This package is a small Node dispatcher with no native code. When you install it, npm also installs the one prebuilt binary package that matches your operating system and processor type, and the trestle command runs that binary. Prebuilt binaries are provided for macOS (Apple Silicon and Intel), Linux (arm64 and x64), and Windows (arm64 and x64).

Do not disable optional dependencies when installing. The prebuilt binary is delivered as an optional dependency, and skipping it leaves the command with no binary to run.

What Trestle does

• Detection. Hundreds of credential patterns from known services (OpenAI, Anthropic, Stripe, AWS, GitHub, Google, Slack, Sentry, and more), plus unfamiliar keys spotted by their variable names, the surrounding code, and when they look random.
• Code-aware. Trestle parses your files so it can tell an environment variable from a build argument, a header, a parameter, or a constant in source.
• Runs where you work. Command line scanner, file watcher, pre-commit hook, Language Server Protocol (LSP) server for editors such as Neovim, Helix, Zed, and JetBrains, and Model Context Protocol (MCP) server for AI assistants such as Claude Code, Cursor, Copilot, and Codex.

Usage

After installing the package, scan the current directory:

npx trestle scan

Set up a project, which adds a pre-commit hook and AI instructions:

npx trestle install

If you installed the package globally with npm install -g @trestlescan/cli, run trestle directly instead of through npx, for example trestle scan.

Commands

| Command | What it does | | --- | --- | | trestle scan | Scan paths for secrets. This is the default command, used when you run trestle with a path or with no arguments. | | trestle watch | Scan once, then keep watching for file changes and re-scan changed files. | | trestle install | Add Trestle's integration (a pre-commit hook and AI instructions) to the current project. | | trestle uninstall | Remove Trestle's integration from the current project. | | trestle lsp | Start the Language Server Protocol server for editors. | | trestle mcp | Start the Model Context Protocol server for AI assistants. |

Findings are written as text by default. The --output-format option also supports CSV, JSON, JUnit, SARIF, and XML. Trestle honors .gitignore and your own skip rules.

Checking whether a secret is live

The trestle command does not make network requests. The bundled trestle-net command adds an optional check that contacts each detected secret's provider to confirm whether the credential is still valid:

trestle-net scan --validate

Each finding is then labeled (active), (inactive), or (could not verify). This check runs only in trestle-net, so trestle stays fully offline.

GitHub Action

To scan every push and pull request, use the official GitHub Action:

name: Secret scan

on:
  push:
  pull_request:

jobs:
  trestle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: toro-guapo/trestle-action@v1

The action also supports uploading SARIF results to the GitHub Security tab. See toro-guapo/trestle-action for inputs, outputs, and supported runners.

How this package works

@trestlescan/cli is plain JavaScript with no scanning logic of its own. It declares one binary package per supported platform as an optional dependency, and npm installs only the one that matches your operating system and processor. When you run trestle or trestle-net, the dispatcher locates the matching binary and runs it. The per-platform packages are internal and are not meant to be installed directly.

Community and Pro

Trestle is open core. The npm packages are the Community edition.

• Community reports detections. Every finding includes its location and the rule that flagged it.
• Pro adds exposure analysis (where a detected secret could leak, such as logs, network responses, or build artifacts) and remediation guidance. Available under a commercial license at trestlescan.com.

Documentation and source

• Documentation: trestlescan.com/documentation
• Source code: github.com/toro-guapo/trestle
• Issues: github.com/toro-guapo/trestle/issues

The source repository is a read-only mirror, refreshed on every Community release. Issues and discussion are welcome, but pull requests are not accepted through the mirror.

License

Apache-2.0. See the LICENSE file included in this package.