Skip to main content
The Shelfforce CLI (sf) lets you turn shelf photos into structured data directly from your terminal. Analyze images, manage stores and tasks, pull reports, and more.

​
Install

npm install -g @shelfforce/cli
This gives you two commands: sf (short) and shelfforce (full name).

​
Authenticate

sf login
This opens your browser to authorize the CLI. Sign in (or sign up), click Connect CLI, and you’re authenticated. The key is stored locally at ~/.shelfforce/auth.json. For CI or non-interactive environments, pass the key directly: 
sf login --key sf_live_a1b2c3d4...
Or set an environment variable: 
export SF_API_KEY=sf_live_a1b2c3d4...

​
Analyze images

​
Single image (URL)

sf run https://example.com/shelf.jpg
The CLI submits the image, polls for results, and displays a product table with share-of-shelf breakdown.

​
Single image (local file)

sf run ./shelf-photo.jpg
The CLI uploads the file, then analyzes it. Supports JPEG, PNG, and WebP.

​
Batch (directory)

sf run ./store-photos/
Pass a directory and the CLI uploads all images, submits them as a batch, polls each until complete, and shows combined results with share of shelf across all images.

​
Batch (text file with URLs)

sf run urls.txt
Pass a .txt file with image URLs (one per line or space-separated). The CLI submits them all as a batch and polls for combined results.

​
Options

FlagDescription
--external-id <id>Your reference ID for tracking
--metadata <json>JSON metadata object (e.g., '{"store":"42"}')
--saveSave results as JSON and CSV to ~/Downloads/
--jsonOutput raw JSON (auto-enabled when piped)
--no-waitSubmit only, don’t wait for results

​
Output

The CLI shows a product table and share-of-shelf breakdown: 
| Brand         | Description                | Category  | Units | Price | Row    | Section | Fixture | Conf |
| Coca-Cola     | Coca-Cola Original 330ml   | Beverages | 4     | 1.49  | top    | center  | fridge  | high |
| Pepsi         | Pepsi Max 330ml            | Beverages | 3     | 1.39  | middle | left    | fridge  | high |

  Share of shelf

| Brand     | Units | Share % | SKUs | On Sale |
| Coca-Cola | 4     | 57.1%   | 1    | 0       |
| Pepsi     | 3     | 42.9%   | 1    | 0       |

  7 products across 2 brands (7 total units).
With --save, results are saved as:
  • ~/Downloads/run-2026-03-30T10-30-00.json — full JSON with products and stats
  • ~/Downloads/run-2026-03-30T10-30-00.csv — product data as CSV

​
Manage resources

Standard CRUD operations for all resource types: 
# Places (stores)
sf places list
sf places get pl_abc123
sf places create --title "Walmart #42" --address "123 Main St"
sf places delete pl_abc123

# Tasks
sf tasks list
sf tasks list --status pending
sf tasks create --title "Audit Aisle 3" --placeId pl_abc123 --dueDate 2026-04-15
sf tasks update tsk_xyz789 --status completed

# Inventory
sf inventory list
sf inventory list --brand "Coca-Cola"
sf inventory create --name "Coca-Cola 330ml" --brand "Coca-Cola" --sku CC-330

# Accounts
sf accounts list --type brand
sf accounts create --name "Coca-Cola" --type brand

# Orders
sf orders list
sf orders create --supplierName "UNFI" --orderDate 2026-04-01

# Webhooks
sf webhooks list
sf webhooks create --url https://your-app.com/hook --events "analysis.completed"
sf webhooks delete wh_abc123

# Members
sf members list
sf members invite --email team@example.com --role member
All commands support --json for machine-readable output: 
sf places list --json | jq '.[0].title'

​
Reports

sf reports share-of-shelf --days 30
sf reports share-of-shelf --days 7 --brands "Coca-Cola,Pepsi"
sf reports compliance --place-id pl_abc123
sf reports store-performance --days 30

​
Check usage

sf usage
Shows remaining credits, PAYG balance, rate limits, and batch size limit.

​
Interactive shell

Run sf with no arguments to enter the interactive shell: 
sf
You get a home screen with your account info and available commands. Type commands without the sf prefix: 
sf > run https://example.com/shelf.jpg
sf > places list
sf > usage
sf > /          # show all commands
sf > /clear     # clear screen
sf > /quit      # exit
The shell supports:
  • Command history (up/down arrows)
  • Cursor movement (left/right, option+left/right for word jump)
  • Word deletion (option+backspace, ctrl+w)
  • Line editing (ctrl+a start, ctrl+e end, ctrl+k delete to end)

​
Profiles

Manage multiple environments: 
sf login --name production
sf login --name staging --url http://localhost:3000

sf profiles              # list all profiles
sf profile:use staging   # switch active profile
sf whoami                # verify current profile

​
Environment variables

VariableDescription
SF_API_KEYAPI key (overrides stored auth)
SF_API_URLApp URL for browser login (e.g., http://localhost:3000 for dev)