Docs · Developers

The sourcefinch CLI

sourcefinch covers every REST API operation from a terminal or a script. It is one self-contained file built on the TypeScript SDK, and it includes the offline evidence-bundle verifier. Node 20 or later.

The package (@tsg/sourcefinch-cli) is not yet published to npm. Until it is, ask us for a build.

Sign in

sourcefinch login            # opens your browser; approve one project (read only)
sourcefinch login --write    # also allow creating sources, runs and deliveries
sourcefinch login --token sec_…   # or save a project API key (CI, servers)
sourcefinch whoami
sourcefinch logout           # revokes the login and deletes the saved credential

Browser sign-in uses OAuth with PKCE and a one-time listener on 127.0.0.1; the token refreshes on its own. Credentials are saved to ~/.config/sourcefinch/credentials.json (readable only by you). SOURCEFINCH_API_KEY or SOURCEFINCH_TOKEN override it, which suits CI. Disconnect a login in Console → Security → Connected apps.

Sources, runs and records

sourcefinch sources list
sourcefinch sources create --file source.json --dry-run    # {name, url, recipe, rights: true}
sourcefinch sources create --file source.json
sourcefinch sources update <source_id> --schedule daily --key-field id
sourcefinch runs create <source_id> --wait                 # exit 6 if the run does not succeed
sourcefinch records <source_id>                            # with evidence ids and usage rights
sourcefinch runs claims <run_id>                           # every value with its evidence and locators
sourcefinch changes --source <source_id> --follow          # field-level changes as they happen

Exports and evidence

sourcefinch export <run_id> --format xlsx                  # csv | json | ndjson | xlsx
sourcefinch bundle <run_id>                                # sourcefinch-run-<run_id>.wacz
sourcefinch verify-bundle sourcefinch-run-<run_id>.wacz --online
sourcefinch evidence content <evidence_id> --out capture.html   # checked against its SHA-256

verify-bundle needs no network: it checks every file and capture hash, every field locator, the manifest signature and the RFC 3161 timestamp. --online also confirms the signing key is the one SourceFinch publishes.

Deliveries

sourcefinch destinations create --name "Ops hook" --url https://example.com/hooks/sf
sourcefinch destinations test <destination_id>
sourcefinch deliveries list --destination <destination_id>
sourcefinch deliveries redeliver <delivery_id>

Scripting

Add --json to any command for machine output; errors then go to stderr as JSON with the API's stable code and request_id. sourcefinch api <operationId> calls any operation from the OpenAPI description directly.