Install and use the CLI

Install the release

Download the CLI package, then install the local package. Node.js 20 or later is required. The package is distributed here; an npm registry release is not required.

npm install --global ./instoryview-cli-0.1.0.tgz
instoryview --version
instoryview auth login
instoryview auth status

Create a Key in Developer settings. auth login reads it without echoing it in the terminal. On macOS, the CLI uses Keychain. On Linux, Windows or CI, supply INSTORYVIEW_API_KEY through your shell or secret manager; no plaintext credential file is written automatically.

Daily commands

instoryview tracking list
instoryview account alice
instoryview followers alice
instoryview following alice
instoryview changes alice

Reads use stored data. To include removed tracking items, add --include-archived to tracking list. Lists accept --limit and --cursor. changes also accepts --list, --from, --to and --timezone.

Request fresh data explicitly

instoryview followers bob --live --max-credits 2
instoryview account bob --live --max-credits 2

Online commands need a Key with data:fetch. They fetch one bounded page. The CLI does not automatically fetch every page. It preserves the idempotency key for retries and supports --idempotency-key for manual recovery with the original body.

Script output

instoryview followers alice --limit 25 --json
instoryview changes alice --list following \
  --from 2026-10-01 --to 2026-10-07 --timezone UTC --json

--json prints the API's data and meta to stdout. Errors and recovery instructions go to stderr. Preserve source, asOf, coverage, creditsUsed and cursor in your pipeline.

Update or remove

Install a new downloaded package to update. Run instoryview auth logout to remove your locally saved login, and npm uninstall --global @instoryview/cli to uninstall. Revoke the Key on the website to stop its use on all machines.