> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelfforce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and use the Shelfforce CLI to analyze shelf images, manage resources, and pull reports from your terminal.

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

```bash theme={null}
npm install -g @shelfforce/cli
```

This gives you two commands: `sf` (short) and `shelfforce` (full name).

## Authenticate

```bash theme={null}
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:

```bash theme={null}
sf login --key sf_live_a1b2c3d4...
```

Or set an environment variable:

```bash theme={null}
export SF_API_KEY=sf_live_a1b2c3d4...
```

## Analyze images

### Single image (URL)

```bash theme={null}
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)

```bash theme={null}
sf run ./shelf-photo.jpg
```

The CLI uploads the file, then analyzes it. Supports JPEG, PNG, and WebP.

### Batch (directory)

```bash theme={null}
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)

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
sf places list --json | jq '.[0].title'
```

## Reports

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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) |