Command Line

Trestle is a single binary. Each feature - scanning, watching, the language server, the MCP Server, and project setup - is exposed as a subcommand of trestle.

Synopsis

trestle [command] [options] [paths...]

When no command is given, Trestle runs scan. When no paths are given, the current directory is used.

Commands

scan

Reads the given files and directories once, reports any findings, and exits. This is the default command.

trestle scan
trestle scan ./server ./website
trestle scan --output-format json --output-file report.json

watch

Runs an initial scan, then watches the given paths and reports new findings as files change.

trestle watch ./src

lsp

Starts Trestle as a Language Server Protocol server over stdio. LSP-compatible editors can launch this command and display Trestle's findings as diagnostics. See Editors for setup details.

mcp

Starts Trestle as a Model Context Protocol server over stdio. AI coding assistants use this command to scan proposed content before writing it to disk. See MCP Server for the tools the server exposes.

install

Configures Trestle for the current project. The command adds a Git pre-commit hook, writes instructions for AI coding assistants, and registers Trestle as an MCP server in the project's .mcp.json. Run from the project root.

uninstall

Removes the integrations added by install.

register (Pro)

Validates a Trestle Pro license key and saves it to the user's configuration directory so that subsequent trestle invocations on this machine recognise the license. Run this once after purchasing Pro.

trestle register YOUR-LICENSE-KEY

The key can also be supplied on standard input.

trestle register < license.key

On success, the command prints the path of the saved license file.

license-info (Pro)

Prints a summary of the Trestle Pro license. With no argument, the saved license file is read. A key supplied as an argument or via --license-key is inspected instead of the saved one.

trestle license-info
trestle license-info YOUR-LICENSE-KEY

Options

Every option below can be passed on the command line or set in a .trestlerc.toml file. See Configuration File for the file format and search order.

Boolean options accept true or false. A boolean option given without a value is treated as true. Example: trestle --verbose is equivalent to trestle --verbose=true.

--auto-excludes[=true|false]

Skip known vendor, cache, build, and metadata directories (node_modules, target, .git, and similar). Default: true.

--skip-vcs-ignored[=true|false]

Skip files and directories ignored by Git (anything matched by .gitignore). Default: true.

--skip-directory-names=name1,name2,...

Skip any directory whose name matches, anywhere under the current directory.

--skip-file-names=name1,name2,...

Skip any file whose name matches, anywhere under the current directory.

--skip-glob=pattern1,pattern2,...

Skip files and directories whose path, relative to the current directory, matches one of these glob patterns. Example: --skip-glob="docs/**,*.snap".

--skip-fingerprints=fingerprint1,fingerprint2,...

Hide individual findings by their fingerprint. Every finding is reported with a short fingerprint that is derived from the secret itself, so it stays the same between scans and across files. Pass one or more of these values to drop those findings from the results.

--exposure-checks[=true|false]

Report secrets that flow into program output, such as values written to logs, passed on a command line, or built into a compiled binary, where they may be seen by users or other systems. Default: true. Set it to false to report only secrets found directly in the source.

--output-format=text|csv|json|junit|sarif|xml

Format used for the findings output. Default: text. See Output Formats for the structure of each format, the rule IDs they emit, and example output.

--output-file=path

Write the output to this file instead of standard output. Use - (the default) for standard output.

--color[=true|false]

Use ANSI colors in the text output. The default is colored when standard output is a terminal, and uncolored otherwise.

--show-summary[=true|false]

Print a summary line after the findings (file count, finding count, elapsed time). Default: true.

--verbose[=true|false]

Print additional scan information to standard error. Default: false.

--validate[=true|false]

Check each detected secret against its provider to confirm whether the credential is still valid. Each finding is labeled active, inactive, or could not verify. This is available only in the separate trestle-net binary, which makes outbound network requests. Default: false.

--validate-timeout-seconds=number

Maximum number of seconds to wait for each validation request. Available only in trestle-net. Default: 30.

--deep[=true|history-only|false]

Also scan the project's git history, not just the files on disk. This covers every branch, tag, and remote-tracking ref, the stash, and commits that are no longer reachable, so a secret that was committed and later removed is still found. Set it to history-only to scan the history without scanning the working tree. Default: false.

--skip-commits-up-to=date-or-commit

When scanning git history with --deep, hide findings in commits up to and including a specified point, and report only what came after it. The value is one of:

  • A date, such as 2026-03-25. Every commit dated that day or earlier is hidden. The day is read in UTC.
  • A date and time, such as 2026-03-25T11:02:39Z or Wed Mar 25 13:02:39 2026 +0200.
  • A commit, such as a1b2c3d4e5f6 (the full identifier or a shorter prefix). That commit and every commit it builds on are hidden.

Dates are matched against each commit's author date, which is the date git log shows.

--skip-commits=commit1,commit2,...

When scanning git history with --deep, hide findings in these specific commits. Unlike --skip-commits-up-to, it does not hide the commits they build on. Each value is a commit, given as the full identifier or a shorter prefix, such as a1b2c3d4e5f6.

--explain[=true|detailed|false] (Pro)

Include remediation guidance with each finding: the steps to remove the secret from source, what to keep in a local .env, and per-platform rotation guides. When scanning git history with --deep, set it to detailed to list every commit a secret was found in. Available in the Pro edition. See Pro.

--license-key=YOUR-LICENSE-KEY (Pro)

Use this Trestle Pro license key for the current invocation instead of the one saved by trestle register. The key is not saved. This is useful in CI environments where the license is delivered through a secret.

--help

Print a help text and exit.

--version

Print the Trestle version and exit.

Output formats

Trestle supports the following output formats: text,csv,json,junit,sarif,xml. See Output Formats for the structure of each format, the rule IDs they emit, and example output.

Exit codes

  • 0 - The scan completed with no findings.
  • 1 - The scan completed with one or more findings.
  • 2 - The scan did not complete (for example, a path could not be read or an option was invalid).

How files are selected

By default Trestle reads every file under the given paths, with two sets of exclusions applied:

  • Files matched by a .gitignore in the tree, unless --skip-vcs-ignored=false.
  • Known vendor, cache, build, and metadata directories, unless --auto-excludes=false.

To exclude additional paths, use --skip-directory-names, --skip-file-names, or --skip-glob. Trestle does not filter files by type or content. Any file that is reachable and not excluded is read.