TIENDocumentation
Docs/Reference

Command reference

Tien follows a pipeline: scan commands write findings, and report commands consume those findings. Binary gob is compact and is the default. JSONL is convenient for scripts and AI agents.

Global commands

tien --help
tien version

Use tien <command> --help for command-specific usage.

tien authorize dns

Creates the exact-host, scoped, expiring authorization used by URL scans:

tien authorize dns --domain app.example.com --valid-for 24h

Repeat --domain to generate a multi-host operator allowlist with a distinct challenge per exact host:

tien authorize dns --domain app.example.com --domain api.example.com --valid-for 24h

Use --format json for automation. Publish each printed TXT value at its printed absolute DNS name, then place the generated hosts challenge map, method: dns, scope, and maximum validity in the operator-owned Tien config. The map prevents an agent tool call from expanding a batch to a host the operator did not list. DNS TXT is the only supported authorization method, and url-scan is currently the only supported scope; other values fail closed. This proof is an operational guardrail for built-in GET/HEAD checks, not legal or contractual authorization.

tien mcp

Runs Tien as a local Model Context Protocol server over stdin/stdout for compatible coding agents.

tien mcp --root /absolute/path/to/your-app

Flags:

  • --root <dir>: repository boundary exposed to MCP tools; defaults to the current directory.
  • --config <path>: operator-owned policy fields loaded once at startup. A selected missing, unreadable, or invalid path fails startup; there is no fallback to defaults.

The server exposes all four tools, including tien_scan_url. URL execution fails closed until the operator config authorizes every target. MCP imposes no target-count ceiling and returns every matching finding unless the caller chooses the optional max_findings presentation filter.

MCP tool errors are returned through the protocol so the agent can correct invalid paths, severity values, or targets. Neither scan tool accepts a per-call config, so a tool call cannot introduce executable plugins or replace URL authorization fields. Referenced rules, plugin binaries, ignore files, and mutable image tags are not snapshotted; protect and pin them separately.

tien scan repo

Scans a repository with enabled Gitleaks, OSV-Scanner, Semgrep, and repo plugins.

tien scan repo --path . --format gob > repo.tien

Flags:

  • --path <dir>: repository path; defaults to the current directory.
  • --format gob|jsonl: finding stream format.
  • --config <path>: required alternate YAML config; a missing, unreadable, or invalid selected file fails the command.
  • --cache auto|true|false: use the configured commit-aware cache or override it.
  • --history auto|true|false: record this run in local history.
  • --policy info|low|med|high|crit|off: exit with code 3 when a finding meets the threshold.
  • --metrics auto|true|false: expose Prometheus metrics while the scan runs.
  • --metrics-listen <address>: metrics address; default 127.0.0.1:9465.
  • --tui: show a live summary on stderr.

tien scan url

Passively scans authorized URLs from a file or stdin.

tien scan url --targets targets.txt --format jsonl > url.jsonl

Flags:

  • --targets <file>: one URL per line; reads stdin when omitted.
  • --format gob|jsonl: finding stream format.
  • --summary=true|false: print a host summary to stderr.
  • --config <path>: required alternate YAML config; a missing, unreadable, or invalid selected file fails the command.
  • --cache auto|true|false: use or bypass the optional URL cache.
  • --history auto|true|false: record this run in local history.
  • --shard N/M: deterministically run one shard of a large target list.
  • --policy info|low|med|high|crit|off: apply a release threshold.
  • --metrics auto|true|false, --metrics-listen, and --tui: runtime visibility.

Blank lines and lines beginning with # are ignored in target files.

Before scanning a public host, run tien authorize dns, publish the TXT record, and use the matching operator config. Authorization is all-or-nothing for the target list and must remain valid through execution; expiry aborts with authorization failure, and MCP returns an error rather than partial success. The url-scan scope authorizes built-in GET/HEAD checks only; a public batch fails closed if a URL plugin is enabled. A hostname that resolves to RFC 1918 or IPv6 ULA space additionally requires an exact allow_resolved_private_hosts entry, an HTTPS target, its exact DNS TXT grant, and pinned addresses. Timeout, body-size, concurrency, retry, and redirect settings remain configurable resource budgets; they are not hard caps on the number of targets or findings.

tien report

Turns a finding artifact into a human-readable or machine-readable report.

tien report --type md --min-severity med --group-by severity repo.tien

Flags:

  • --type text|md|sarif|json: output type.
  • --input-format gob|jsonl: override format detection, especially for stdin.
  • --min-severity info|low|med|high|crit: filter lower severities.
  • --group-by source|severity|target|none: organize text and Markdown output.
  • --only-tags tag1,tag2: include findings containing selected tags.
  • --top <n>: number of recurring issues shown in the summary.

When reading JSONL from stdin, set the input format explicitly:

tien scan repo --path . --format jsonl \
  | tien report --input-format jsonl --type json > tien-report.json

tien merge

Combines findings, removes duplicates by fingerprint, and produces stable ordering.

tien merge repo.tien url.tien > complete.tien

Use --format gob|jsonl for output and --input-format to override input detection. A single - input reads stdin.

tien diff

Compares two runs using stable fingerprints.

tien diff baseline.tien current.tien

The result identifies new, fixed, unchanged, and severity- or confidence-changed findings.

tien encode

Converts between the finding stream formats.

tien encode --to jsonl repo.tien > repo.jsonl
tien encode --to gob --input-format jsonl repo.jsonl > repo.tien

tien plot

Generates a self-contained HTML report.

tien plot --min-severity low complete.tien > report.html

Use --only-tags to focus the visual report.

tien history

Shows locally recorded scans when history is enabled.

tien history --limit 10
tien history --format json --limit 0

tien hybrid

Runs Gitleaks directly, preferring a local binary and falling back to Docker. This command emits raw Gitleaks JSON rather than normalized Tien findings.

tien hybrid --path . > gitleaks.json

Use tien scan repo for the normal multi-engine, normalized workflow.

Exit codes

  • 0: command completed and any configured policy passed.
  • 1: runtime, configuration, scan, or file error.
  • 2: invalid command usage.
  • 3: scan completed, but the policy threshold was met.
  • 130: scan was interrupted; Tien attempts to write partial results first.

Do not treat exit code 3 as a scanner crash. It is a deliberate release-gate result.