@getpilfer/cli

Pilfer REST API CLI for terminal and script use.

Install

npm install -g @getpilfer/cli
pilfer whoami

Or run without installing:

npx @getpilfer/cli whoami

Auth

pilfer login
# or
export PILFER_API_TOKEN="plf_..."

Tokens are stored in ~/.config/pilfer/credentials.json. API keys use the plf_ prefix.

Base URL

Default: https://api.getpilfer.com.

Override for local or early deployments:

export PILFER_API_BASE_URL="https://api.example.com"
pilfer --base-url https://api.example.com projects list
pilfer config set-base-url https://api.example.com

Commands

Generated resources:

pilfer organizations list
pilfer projects list
pilfer spaces list --project-name "Studio upgrade"
pilfer scouts create --name "New candidate" --category-name "Lighting"
pilfer assets update <id> --cost 120
pilfer recurs create --name "Hosting" --amount 40 --period monthly --direction outgoing
pilfer month-plans create --year 2026 --month 6 --expected-income 5000
pilfer transactions create --amount 28 --bucket WANTS --category-name "Food" --description "Lunch"
pilfer goals create --name "Desk fund" --target-amount 600
pilfer comments list --entity-type scout --entity-id <id>
pilfer assets create --name "Camera" --dry-run

Use --project-name, --space-name, --category-name, --scout-name, --asset-name, --label-name, or --organization-name instead of matching *Id flags when the generated resource supports that relation.

List commands support server-side controls:

pilfer scouts list --search lamp --filter status=Considering --sort -updatedAt --limit 25
pilfer scouts list --page-mode cursor --limit 25
pilfer scouts list --cursor 25 --page-mode cursor --limit 25

Nested scout sources:

pilfer sources list --scout-id <id>
pilfer sources create --scout-id <id> --url <url> --name "Vendor" --price 49 --dry-run
pilfer sources update --scout-id <id> <source-id> --starred true
pilfer sources delete --scout-id <id> <source-id>

Asset maintenance notes:

pilfer maintenance-notes list --asset-id <id>
pilfer maintenance-notes create --asset-id <id> --title "Clean filter" --status open --dry-run
pilfer maintenance-notes update --asset-id <id> <note-id> --status closed
pilfer maintenance-notes delete --asset-id <id> <note-id>

Recur expenses:

pilfer recur-expenses list --recur-id <id>
pilfer recur-expenses create --recur-id <id> --name "Add-on" --cost 12 --period monthly --dry-run
pilfer recur-expenses update --recur-id <id> <expense-id> --cost 15
pilfer recur-expenses delete --recur-id <id> <expense-id>

Agent workflow helpers:

pilfer scouts capture --name "Desk lamp" --url <url> --price 89 --category-name "Lighting" --project-names "Studio" --dry-run
pilfer scouts shortlist
pilfer scouts pipeline
pilfer scouts purchase <scout-id> --cost 120
pilfer reports scouting
pilfer reports assets
pilfer reports balance --project-id <id>
pilfer reports balance --space-id <id>

Top-level helpers:

pilfer whoami
pilfer status
pilfer commands --json
pilfer schema --json
pilfer sync list
pilfer sync list --since 1781799784352 --output json
pilfer batch create --body '{"operations":[{"method":"GET","path":"scouts","query":{"limit":5}}]}'
pilfer login [token]
pilfer logout
pilfer config show
pilfer setup-agent

Development

pnpm --filter @getpilfer/cli generate
pnpm --filter @getpilfer/cli check-types
pnpm --filter @getpilfer/cli build

Resource commands are generated from apps/api/spec/openapi.yaml.

Agent-facing discovery:

pilfer commands --json   # full command tree
pilfer schema --json     # resource/actions/options overview
pilfer setup-agent       # shell setup and recommended workflow hints