---
name: fluent-cli-retailer
description: Manage Fluent retailer lifecycle via CLI. Use for creating and listing retailers, validating profile context, and safely preparing retailer admin access for module/workflow operations. Triggers on "create retailer", "list retailers", "retailer context", "retailer admin", "fluent retailer".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: <create|list> [retailer-ref] [--profile name]
cursor-tier: auto
---

# CLI Retailer Operations

Create and inspect retailers with Fluent CLI, and ensure follow-up context is valid for deployments.

> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.

## Pre-flight: Feedback Check

Before starting, check for past learnings from this skill:

1. Check if `accounts/<PROFILE>/feedback/fluent-cli-retailer.jsonl` exists
2. If yes, read last 20 records
3. Filter to: FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
4. Extract top 3 relevant learnings — use as internal guidance during execution
5. Do NOT show raw feedback to the user — silently adjust approach based on past issues

## When to Use

- New retailer setup
- Listing retailers under a profile/account
- Preparing context before module install or workflow operations

## Core Commands

Check available syntax first:

```bash
fluent retailer --help
```

### Create retailer

```bash
fluent retailer create <retailer-ref> \
  --email <retailer-admin-email> \
  --profile <profile-name>
```

### List retailers (local configs)

```bash
fluent retailer list
```

Note: `retailer list` takes NO flags — it lists all locally configured retailers across all profiles.

### List retailers (remote, via profile)

```bash
fluent profile retailers <profile-name>
```

### Manual retailer registration

When the CLI doesn't know about a retailer (e.g., `workflow list` fails with "retailer does not exist"), you can register it manually:

```bash
fluent profile update <profile-name> --retailer <retailer-ref> --id <retailer-id>
```

Or create the file directly:
```json
// ~/.fluentcommerce/<profile>/retailer.<retailer-ref>.json
{ "id": "<id>", "ref": "<retailer-ref>", "user": "<username>" }
```

## Post-Create Validation

After creating a retailer, verify it is ready for use:

1. List retailers to confirm creation: `fluent profile retailers <PROFILE>`
2. Verify workflows are accessible: `fluent workflow list -p <PROFILE> -r <NEW_RETAILER_REF>`
3. Verify settings context: `fluent setting list -p <PROFILE> -r <NEW_RETAILER_REF>`
4. If workflow list returns empty, this is expected for new retailers — modules must be installed first

### Detailed steps

1. Confirm retailer appears in `fluent retailer list`.
2. Set active context:

```bash
fluent profile use <profile-name> --retailer <retailer-ref>
fluent profile active
```

3. **Verify API access works** — run a lightweight query to confirm the retailer is fully provisioned:

```bash
fluent workflow list -p <profile-name> -r <retailer-ref>
```

This confirms the CLI can authenticate against the retailer context and the retailer is ready for operations. A new retailer will return an empty list (no workflows yet), which is expected. An auth error here means the retailer user credentials need to be configured via `fluent profile update`.

4. **Verify settings context** — confirm the settings subsystem is accessible:

```bash
fluent setting list -p <profile-name> -r <retailer-ref>
```

5. Proceed with module config/install only after active retailer is correct and API access is verified.

## Important Operational Note

Prefer CLI retailer creation for full operational setup. Avoid ad-hoc GraphQL retailer creation for bootstrap flows because downstream behavior can diverge from CLI-created retailer expectations.

## Troubleshooting

| Issue | Likely Cause | Fix |
|---|---|---|
| Retailer create fails auth | Wrong profile credentials | Verify profile and retry with correct account admin |
| Retailer not visible | Wrong profile/account | Re-check profile and rerun list |
| Subsequent module commands fail | Active retailer not set | Run `fluent profile use ... --retailer ...` |

## Post-Execution: Feedback Capture

After completing this skill (whether success or failure), write a feedback record:

1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
2. **Build record:** Create a `feedback-record-v1` JSON object with:
   - `skill`: `"fluent-cli-retailer"`
   - `feature`: feature slug if applicable, null otherwise
   - `phases`: trace of each phase with PASS/FAIL/SKIP
   - `learnings`: any gotchas discovered during execution
   - `userCorrections`: any corrections the user provided
3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-cli-retailer.jsonl`
5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)

**Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

_(No promoted learnings yet.)_

<!-- end feedback-promoted -->
