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 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.

Exit codeMeaning
0Success
1Other error
2Usage error
3Not signed in, expired, or not allowed
4Not found
5Plan limit or policy refusal
6The run did not succeed (runs create --wait, watch)
7Verification failed (verify-bundle, evidence content)