Shelfforce CLI

Turn shelf photos into structured data from your terminal.

Install

npm install -g @shelfforce/cli

Quick Start

1. Authenticate

sf login

This opens your browser to sign in and authorize the CLI. Your key is stored locally.

For CI or non-interactive environments:

sf login --key sf_live_a1b2c3d4...

Or set an env var:

export SF_API_KEY=sf_live_a1b2c3d4...

2. Check your account

sf whoami        # Show email, plan, credits
sf usage         # Detailed credits, rate limits, batch max

3. Analyze a shelf image

# URL
sf run https://example.com/shelf.jpg

# Local file
sf run ./shelf-photo.jpg

# Directory (batch)
sf run ./store-photos/

# Text file with URLs (one per line)
sf run urls.txt

# With tracking ID
sf run https://example.com/shelf.jpg --external-id customer-123

# Save results to ~/Downloads/
sf run https://example.com/shelf.jpg --save

# JSON output
sf run https://example.com/shelf.jpg --json

4. Browse your data

sf places list
sf tasks list --status pending
sf inventory list --brand "Coca-Cola"
sf accounts list --type brand
sf orders list

5. Run reports

sf reports share-of-shelf --days 30
sf reports compliance --place-id pl_abc123
sf reports store-performance --days 30

6. Interactive shell

sf

Type commands without the sf prefix. Use / to see all commands, /quit to exit.

Profiles

sf login --name production
sf login --name staging

sf profiles
sf profile:use staging

Environment Variables

| Variable | Description | |----------|-------------| | SF_API_KEY | API key (overrides stored auth) | | SF_API_URL | App URL for browser login (for dev environments) |

All Commands

sf login              Authenticate via browser
sf logout             Remove stored auth
sf whoami             Show current auth
sf profiles           List profiles
sf profile:use        Switch profile
sf usage              Credits, rate limits
sf run                Analyze image (URL, file, directory, or .txt of URLs)
sf places             Manage stores
sf tasks              Manage tasks
sf inventory          Manage catalog
sf accounts           Manage accounts
sf orders             Manage orders
sf webhooks           Manage webhooks
sf members            Manage team
sf reports            Run reports

Run sf <command> --help for options.