---
name: fluent-cli-settings
description: Manage Fluent CLI settings operations. Use for listing and reading settings by profile/retailer context, wildcard filtering, and validating missing/incorrect setting values before or after module/workflow changes. Triggers on "list settings", "read setting", "settings list", "fluent setting", "check settings".
user-invocable: true
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: <list|get> [setting-name-or-pattern] [--profile name] [--retailer ref]
cursor-tier: auto
---

# CLI Settings Operations

Read and validate Fluent settings using CLI commands, with profile/retailer context safety checks.

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

## When to Use

- User asks to list current settings
- User asks to read a specific setting key/value
- Validate required settings after module/workflow deployment
- Compare settings across environments via profile+retailer context

## Prerequisites

- Active or provided profile
- Retailer context for retailer-scoped settings

Always verify context first:

```bash
fluent profile active
```

## Core Commands

Use command help first if your CLI build differs:

```bash
fluent setting --help
```

### List settings (summary view)

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

With wildcard filtering (SQL-style `%` wildcards, not glob):

```bash
fluent setting list -p <profile-name> -r <retailer-ref> --name "%webhook%"
fluent setting list -p <profile-name> -r <retailer-ref> --name "%manifest%" --json
fluent setting list -p <profile-name> -r <retailer-ref> --context retailer
```

| Flag | Description |
|------|-------------|
| `-n, --name` | Filter by name (`%` wildcards). Repeatable. |
| `-f, --first` | Limit results (disables auto-pagination) |
| `--context` | Filter: `account`, `retailer`, or `all` |
| `-j, --json` | Output as JSON (default: false) |

### Get settings (full detail with values)

```bash
fluent setting get -p <profile-name> -r <retailer-ref>
fluent setting get -p <profile-name> -r <retailer-ref> --name "%order%" --json
```

| Flag | Description |
|------|-------------|
| `-n, --name` | Filter by name (`%` wildcards). Repeatable. |
| `-f, --first` | Limit results (disables auto-pagination) |
| `--context` | Filter: `account`, `retailer`, or `all` |
| `-j, --json` | Output as JSON (default: true) |

**Difference:** `list` = summary (name, context, type), `get` = full detail including `value` and `lobValue` (for JSON settings).

## Validation Workflow

1. `fluent setting list` for broad view.
2. `fluent setting get` for each required key.
3. Compare values with expected module/workflow config.
4. Report missing keys and mismatches.

Suggested output format:

```
Setting: webhook.order.created
Status: FOUND
Value: https://...
Context: retailer=<retailer-ref>
```

## Scope Resolution Cascade

When a setting exists at multiple levels, the most specific scope wins:

```
RETAILER (most specific) → ACCOUNT (fallback) → Platform default (if any)
```

**Example:** If `webhook.order.created` exists at both RETAILER (contextId=5) and ACCOUNT level, the RETAILER value is used at runtime for that retailer. The ACCOUNT value applies only to retailers that don't have their own override.

**Debugging unexpected values:** Always check both contexts explicitly:
```bash
fluent setting get -n "webhook.order.created" -c RETAILER -p <profile> -r <retailer>
fluent setting get -n "webhook.order.created" -c ACCOUNT -p <profile>
```

If both return values and the RETAILER one isn't what you expect, the RETAILER setting is what the rules actually use.

## Common Checks

- Webhook endpoints
- Carrier defaults
- Consignment prefixes
- Feature flags
- Cancellation reason sources

## Troubleshooting

| Issue | Likely Cause | Fix |
|---|---|---|
| Empty list | Wrong profile/retailer context | Verify `fluent profile active` and rerun with explicit `--profile/--retailer` |
| Setting not found | Key mismatch or wrong scope | Check exact name/case and target retailer |
| Unexpected value | Drift between environments | Compare with source env and re-apply expected config |
