---
name: fluent-profile
description: Manage Fluent CLI profiles for connecting to Fluent Commerce accounts. Use for creating, updating, switching, listing, or exporting profiles. Triggers on "create profile", "switch profile", "list profiles", "export profile", "fluent profile".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: <operation> [profile-name]
cursor-tier: auto
---

# Profile Management

Manage Fluent CLI profiles for connecting to Fluent Commerce accounts.

> **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-profile.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

- Creating new connection to Fluent account
- Switching between environments (dev/UAT/prod)
- Exporting credentials for Postman
- Managing multiple accounts

## Quick Reference

| Command | Purpose |
|---------|---------|
| `fluent profile create` | Create new profile |
| `fluent profile list` | List all profiles |
| `fluent profile use` | Set active profile |
| `fluent profile active` | Show current profile |
| `fluent profile update` | Modify profile |
| `fluent profile export` | Export for Postman |
| `fluent profile clear` | Clear active context |

## Operations

### 1. Create Profile

**Required information:**
- Profile name (e.g., `cli-b2c`, `prod-au`)
- Account ID
- Base URL
- Username & password
- Client secret

```bash
fluent profile create <profile-name> \
  --id <account-id> \
  --base-url <base-url> \
  --username <username> \
  --password <password> \
  --client-secret <client-secret>
```

**Example:**
```bash
fluent profile create cli-b2c \
  --id ABC123 \
  --base-url https://abc123.sandbox.api.fluentretail.com \
  --username admin_user \
  --password secret123 \
  --client-secret abc123xyz
```

### 2. List Profiles

```bash
fluent profile list
```

**Output:**
```
PROFILE NAME       ACCOUNT ID    BASE URL
cli-b2c            ABC123        https://abc123.sandbox.api.fluentretail.com
prod-au            XYZ789        https://xyz789.api.fluentretail.com
```

### 3. Set Active Profile

**Profile only:**
```bash
fluent profile use <profile-name>
```

**Profile + retailer:**
```bash
fluent profile use <profile-name> --retailer <retailer-ref>
```

### 4. Check Active Profile

```bash
fluent profile active
```

**Output:**
```
Active profile: cli-b2c
Active retailer: b2c
```

### 5. Update Profile

**Add user:**
```bash
fluent profile update <profile-name> \
  --username <new-username> \
  --password <new-password>
```

**Add retailer:**
```bash
fluent profile update <profile-name> \
  --retailer <retailer-ref> \
  --id <retailer-id> \
  --username <retailer-admin> \
  --password <password>
```

**Switch active user:**
```bash
fluent profile update <profile-name> --user <username>
```

### 6. Export Profile (Postman)

```bash
fluent profile export <profile-name> \
  --format postman \
  --retailer <retailer-ref>
```

**Output:** `postman.<profile>.<retailer>.environment.json`

**Import into Postman:**
1. Open Postman -> Environments -> Import
2. Select exported file
3. Environment ready for API testing

### 7. Clear Active Profile

```bash
fluent profile clear
```

### 8. Purge Sessions

Clean up old session files:
```bash
fluent profile purge-sessions
```

## Profile Storage

Profiles stored in: `~/.fluentcommerce/<profile-name>/`

```
~/.fluentcommerce/
├── cli-b2c/
│   ├── profile.json
│   ├── user.admin_user.json
│   └── retailer.b2c.json
└── .sessions/
    └── <session-files>
```

## Error Handling

| Error | Solution |
|-------|----------|
| Profile already exists | Use different name or update existing |
| Profile not found | Check name with `profile list` |
| Authentication failed | Verify credentials, update profile |
| No active profile | Use `profile use <name>` |
| Retailer not found | Add with `profile update` |

## Security Best Practices

1. **Never log passwords** - Use `[REDACTED]` in any output
2. **Protect profile directory** - `~/.fluentcommerce/` contains credentials
3. **Environment-specific profiles** - Don't mix dev/prod
4. **Handle exports carefully** - Postman files contain plain-text credentials
5. **Rotate credentials regularly** - Update profiles with new passwords

## Credential Rotation

To rotate credentials for a Fluent profile:

1. Generate new credentials in Fluent Commerce admin console
2. Update profile: `fluent profile update -n <PROFILE> --client-id <NEW_ID> --client-secret <NEW_SECRET>`
3. Validate new credentials: `fluent profile test -n <PROFILE>` (or attempt `fluent workflow list -p <PROFILE>`)
4. If validation succeeds, the rotation is complete
5. If validation fails, revert: `fluent profile update -n <PROFILE> --client-id <OLD_ID> --client-secret <OLD_SECRET>`

**Warning:** Never rotate credentials mid-deployment. Complete all in-flight deployments first.

### Extended Rotation Procedure

When credentials expire or are rotated by an admin, follow these steps:

#### Step 1: Identify affected profiles

```bash
fluent profile list
```

Note which profiles use the rotated credentials (check username in each `~/.fluentcommerce/<PROFILE>/profile.json`).

#### Step 2: Update profile credentials

```bash
fluent profile update <profile-name> \
  --username <username> \
  --password <new-password>
```

If the client secret was rotated:
```bash
fluent profile update <profile-name> \
  --client-secret <new-client-secret>
```

#### Step 3: Update retailer user credentials (if applicable)

```bash
fluent profile update <profile-name> \
  --retailer <retailer-ref> \
  --username <retailer-admin> \
  --password <new-password>
```

#### Step 4: Verify updated credentials

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

If MCP servers are configured, restart them after updating credentials so they pick up the new profile data.

#### Step 5: Verify MCP connectivity (if applicable)

After restarting MCP servers, run `connection.test` to confirm authentication works with the new credentials.

### Common rotation triggers

| Trigger | What to update |
|---------|---------------|
| Password expired | `--password` on profile and retailer users |
| Client secret rotated | `--client-secret` on profile |
| User deactivated/replaced | `--username` + `--password` on profile |
| Environment migration | Create new profile with new credentials |

For a complete CLI command reference, see `/fluent-cli-index`.

## 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-profile"`
   - `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-profile.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 -->
