CLI

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

Flag	Description
`--external-id <id>`	Your reference ID for tracking
`--metadata <json>`	JSON metadata object (e.g., `'{"store":"42"}'`)
`--save`	Save results as JSON and CSV to `~/Downloads/`
`--json`	Output raw JSON (auto-enabled when piped)
`--no-wait`	Submit 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

Variable	Description
`SF_API_KEY`	API key (overrides stored auth)
`SF_API_URL`	App URL for browser login (e.g., `http://localhost:3000` for dev)

Getting Started

Core Concepts

Guides

Install

Authenticate

Analyze images

Single image (URL)

Single image (local file)

Batch (directory)

Batch (text file with URLs)

Options

Output

Manage resources

Reports

Check usage

Interactive shell

Profiles

Environment variables

​Install

​Authenticate

​Analyze images

​Single image (URL)

​Single image (local file)

​Batch (directory)

​Batch (text file with URLs)

​Options

​Output

​Manage resources

​Reports

​Check usage

​Interactive shell

​Profiles

​Environment variables

Install

Authenticate

Analyze images

Single image (URL)

Single image (local file)

Batch (directory)

Batch (text file with URLs)

Options

Output

Manage resources

Reports

Check usage

Interactive shell

Profiles

Environment variables