reopt-cli

name	reopt-cli
description	Baseline guidance for the reopt CLI — authentication, login, global flags, security rules, and exit codes. Use before other reopt CLI skills or whenever a task involves `reopt login`, `reopt status`, brandapp credentials, or CI automation.

reopt CLI

Baseline guidance for the reopt CLI. Load this before resource-specific reopt skills.

When to Apply

Use this skill when:

• a task involves any reopt CLI command
• you need to confirm login state
• automation needs Brandapp OAuth credentials
• you are writing CI/CD steps around reopt

Authentication

The CLI has two credential systems.

User session

Use for interactive browsing and linking:

reopt login
reopt login --server https://app.reopt.ai
reopt status
reopt logout              # remove the local session token
reopt logout --all        # also wipe every brandapp credential under ~/.reopt/credentials.json

Session tokens live in ~/.reopt/auth.json. When the local token is past its hard expiry but Better Auth's session-extension window still applies, the CLI silently refreshes the token on the next command (and on brandapp doctor). No re-login is needed in that window — surface this fact when scripting CI so users do not over-engineer retry logic.

Brandapp OAuth credentials

Use for SDK calls and EAV sync:

export REOPT_CLIENT_ID=your_client_id
export REOPT_CLIENT_SECRET=your_client_secret

Or create them interactively:

reopt brandapp link

These credentials are written to ~/.reopt/credentials.json and .reopt.json in the project root.

Check Auth State

Run this before mutating operations:

reopt status
reopt status --ping       # also probe the server and report latency

If status shows auth: not logged in, run reopt login first.

Other Top-Level Commands

Command	Purpose
reopt mcp	Start a Model Context Protocol server over stdio. Used by IDE / agent integrations; bypasses commander entirely (fast path) and stays alive until stdin closes.
reopt schema [resource]	Inspect Brandapp resource schemas. Omit [resource] to list all available; pass a name to print one schema. Intended for tooling and agents.
reopt completion <bash|zsh|fish>	Print a shell completion script. The script walks the live commander tree (so new subcommands are picked up automatically) and includes aliases.
reopt config list (alias ls)	Show every preference stored in ~/.reopt/preferences.json.
reopt config get [key]	Read one preference (or list all when key is omitted).
reopt config set <key> <value>	Persist a preference. Known keys: server (default API URL — overridden by REOPT_CLI_SERVER and --server), format (default output format), interactive (force prompt on/off, otherwise TTY-detected).
reopt config unset <key> (alias rm)	Remove a preference.

reopt config set format table is the supported way to make a developer machine default to the human-readable view without changing every command.

Global Flags

These options are wired at the program level (program.option(...)), so they apply to every subcommand:

Flag	Default	Purpose
--format <type>	json (or config get format)	Output format: json / table / csv / yaml. JSON is the agent-friendly default.
--fields <fields>	—	Restrict output to a comma-separated list of field names.
--limit <n>	—	Cap the number of results returned by list endpoints.
--offset <n>	—	Skip N results into a list endpoint.
--page-all	off	Iterate through every page; in JSON mode, output is NDJSON (one record per line).
--page-limit <n>	10	Maximum pages to fetch when --page-all is set.
--page-delay <ms>	100	Delay between page requests when --page-all is set.
--timeout <ms>	30000	Per-request HTTP timeout.
--max-retries <n>	1	Retry budget for idempotent (GET) requests.
-q, --quiet	off	Suppress non-essential output.
-v, --verbose	off	Verbose output (stack traces, debug info).
--no-interactive	off	Never prompt for missing arguments — fail with a validation error instead. Required for unattended scripts.

Per-subcommand flags layered on top of the global set:

Flag	Where	Purpose
--json	several list commands	Legacy alias preserved for backward compatibility — prefer --format json.
--dry-run	EAV sync, brandapp link/unlink	Preview only — no mutation.
--delete-orphans	EAV sync/status	Include or apply removal of server-only attrs.
-s, --schema <path>	EAV commands	Custom EAV schema path (default ./eav.schema.ts).
-o, --out <path>	EAV pull, eav plan, sync	Custom output path.
-w, --watch	EAV sync, brandapp dev	Watch file changes and re-run.
--server <url>	login	Override the auth server URL.

Security Rules

1. Never hardcode credentials.
2. Never print credential values.
3. Never commit files under ~/.reopt/.
4. Inject secrets through a secret manager in CI.
5. Use --dry-run before any mutating EAV operation.
6. When invoking the CLI programmatically, pass arguments as arrays.

Schema Discovery

reopt brandapp eav pull --out ./eav.schema.ts
reopt brandapp eav status --json
reopt brandapp eav status --delete-orphans --json

Exit Codes

Code	Meaning
0	Success
1	API or network error
2	Auth error
3	Validation error
4	Config error
5	Internal error