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 (@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.
Watch a URL in one step
sourcefinch watch https://example.gov/notices --yes-i-have-the-right sourcefinch watch https://example.gov/notices --yes-i-have-the-right \ --name "Notices" --schedule hourly --wait 60
watch previews the URL, creates a source from the records it finds, runs it once and prints the first records as a table, then the commands to run next. --yes-i-have-the-right confirms you may collect the source. Without it, the CLI asks on a terminal and refuses in a script. --wait is how many seconds to wait for the first run (0 to 60, default 30). If the page has no records, nothing is created. If the first run fails, the source stays and the exit code is 6.
For full control, use sourcefinch preview <url> to see the proposed recipe, then sources create and runs create below.
Verified catalog
sourcefinch catalog list --q "federal register" # Verified sources (also at /sources) sourcefinch catalog get federal-register-rules --source-json > source.json sourcefinch sources create --file source.json # monitor it with the Verified recipe
Sources, runs and records
sourcefinch sources list
sourcefinch preview https://example.gov/notices # records found and a proposed recipe; nothing is saved
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 happenExports 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.
| Exit code | Meaning |
|---|---|
0 | Success |
1 | Other error |
2 | Usage error |
3 | Not signed in, expired, or not allowed |
4 | Not found |
5 | Plan limit or policy refusal |
6 | The run did not succeed (runs create --wait, watch) |
7 | Verification failed (verify-bundle, evidence content) |