market (App-store v2)

CRITICAL — before doing anything, MUST use the Read tool to read ../olares-shared/SKILL.md for profile selection, login, automatic token refresh, and the auth-error recovery table.

Source of truth for flags is always olares-cli market <verb> --help. This file only carries what --help cannot give: source resolution, the lifecycle state machine, OpType-vs-State race safety, the verb index, the -s/-a matrix, and the "what apps do I have" routing.

Routing

Mental model: market is lifecycle and inventory at the app-store level (install / upgrade / chart push). For runtime K8s objects, settings, or metrics, route to a sibling.

Verb families

For verb-specific behavior, always start with olares-cli market <verb> --help. Then drill into a reference if listed:

Source resolution (cross-cutting)

The market backend serves multiple "sources" of charts. The CLI resolves which one to talk to from -s / --source, falling back to a default that depends on the verb:

• When -s is omitted, every verb that accepts it prints Using source: <id> to stderr so the agent can confirm which backend was hit.
• -a / --all-sources bypasses single-source resolution and spans every source the user has — read-only verbs only.
• Unknown source ids silently produce an empty result with a no apps in source 'X' stderr hint. Run market list -a to enumerate the configured sources.

-s / -a matrix

-s is NOT on uninstall / stop / resume / cancel: they act on whichever per-user state row matches the app name, regardless of source.

App lifecycle / state machine

The backend tracks two orthogonal axes per app: State (where the row currently is) and OpType (which mutation is in flight). The CLI groups the full enum into four buckets:

Each lifecycle verb maps to its own subset of terminal-success buckets — see the lifecycle reference.

OpType vs State (race-safety)

The same State can mean different things depending on which mutation is in flight. Concrete example: an upgrade issued against an app already in running will return state=running, opType=running for one or two ticks before the backend flips to state=upgrading, opType=upgrade. A naive watcher would declare success at tick zero.

The CLI's mutating-verb watchers refuse to accept any "success" classification until either:

1. the row's OpType matches the op the CLI just issued, or
2. the row disappears entirely (only legal for uninstall / status).

cancel and status deliberately set matchOpType=false because they are op-agnostic by design — cancel declares success on any "row stopped moving" state.

--watch semantics (lifecycle verbs)

• Polling, not streaming. Tick on --watch-interval (default tuned to the backend's progress cadence).
• --watch-timeout D caps total wall-clock time.
• One-shot (no --watch) returns as soon as the backend ACKs the mutation request — the row may still be progressing for minutes.
• With --watch, the CLI blocks until the row reaches a terminal bucket (success OR failure) matching the OpType safety rules above.
• Idempotent: resume against an already-running row returns immediately with success; install against an already-installed row returns immediately with state=running. Watcher never hangs on "no-op" mutations.
• --watch-iterations / --watch-interval / --watch-timeout are rejected without --watch.

"What apps do I have?" routing

list --mine is NOT the same as "completed installs only". It hides only the 6 SPA-hidden uninstalledAppStates (pendingCanceled, downloadingCanceled, downloadFailed, installFailed, installingCanceled, uninstalled). In-flight installs and post-install failures stay visible because the user clicked something and expects to monitor / retry / cancel them.

Output conventions

• -o table (default) or -o json — present on EVERY market verb.
• -q / --quiet suppresses all stdout / stderr; exit code carries the signal.
• --no-headers — only list and categories (row-oriented browse). NOT on get (key:value detail, no headers separable) or status (runtime probe, always headered). No-op silently on mutating verbs.
• Mutating verbs emit a stable OperationResult JSON shape with finalState / finalOpType for scripted parsing.

Common errors

For the full auth-error matrix see ../olares-shared/SKILL.md.