---
name: use
description: Use an indexed Apilift service for account-state work in a UI-only product, and hand missing coverage to one discovery owner. Prefer a first-party CLI, SDK, MCP server, or documented API whenever one covers the task.
---

# Use an indexed service

Use Apilift only for product work that lacks a more appropriate installed capability. An indexed Apilift service may itself expose a current documented API through a direct service auth/transport recipe, so do not assume every Apilift command needs a browser. Treat the Apilift CLI as the only consumer documentation and execution surface; do not inspect discovery files, captures, browser storage, registry data, or implementation code to learn a command.

Use `apilift` for every Apilift call. Treat sandbox, network, registry, executable, and browser-transport failures as environment failures, not product results.

## Inspect only as far as the next decision needs

Start with `apilift services`, then `apilift <service> --help`. When names are known, read entity or operation help; use one batch docs call for several known selectors, search only when vocabulary is unknown, and full schema only when progressive docs cannot answer the call. Execute only documented commands and flags: `apilift <service> <entity> <verb> [flags]`.

Before piping or parsing any consumer result with `jq`, a script, or another machine reader, pass `--json`; ordinary output is for humans and may include tables, pagination hints, counts, or spend information around the selected value.

If help declares service context, run `apilift <service> context show`, obtain each value from its documented command or source, and set it once. Never copy opaque identifiers from examples, browser pages, captures, URLs, or guessed JSON. A command may explicitly document a stable human-readable account or workspace slug as coming from the product's own visible URL; only that documented non-opaque slug may be read there. A required value with no documented reachable source is missing coverage.

Respect documented effects, costs, constraints, unavailable boundaries, and policy. A policy refusal is terminal for the requested action; do not prepare arguments, retry, send raw HTTP, or rediscover around it.

## Invoke the command through its selected service recipe

The first consumer command selects the Action's `authRecipe`, or the service `defaultRecipe`, and then dispatches that recipe as direct or browser transport. Browser recipes automatically prepare Chrome execution, claim or open the service page, include browser credentials, reacquire expired values, and perform one safe auth retry. Direct recipes never prepare Chrome; their credentials are read from the local operating-system vault only at dispatch and never appear in dry-run, diagnostics, errors, or history. Do not connect manually, generate preparatory UI traffic, reload to mint a header, extract credentials, or add transport fields to an Action.

If a direct command returns `credential_missing`, `vault_locked`, `vault_unavailable`, or `credential_contract_changed`, send the user to that service in the Apilift dashboard and follow its nontechnical setup flow. Never ask the user to paste a secret into chat, a shell, an environment variable, a file, browser storage, or the dashboard. An `extension-update-required` result blocks only credential provisioning for that direct recipe; browser recipes and direct recipes without credentials remain usable.

Follow the command's exact retry or stop instruction. Use `apilift browser status --agent codex|claude --json` only after a reported browser installation, handshake, or transport defect, and execute returned machine repairs yourself. Ask the user to sign in only after an auth-required result proves the current Chrome profile cannot recover, then retry the same interrupted command. Do not switch browser contexts after a Chrome failure.

Never bypass a consumer refusal with an internal endpoint. If a mutation has an ambiguous result, inspect product state through a documented read before considering another mutation; do not blindly retry it.

If the control plane reports `private-service-plan-required`, stop before product access and offer the returned upgrade or Make public action. Never execute from a cached private snapshot, rediscover the same interface as Community, or use raw HTTP to bypass the workspace entitlement. Treat an interface that exists only in another workspace exactly like an unknown interface; do not reveal or speculate about its existence.

## Extend only the missing capability

Coverage is missing when the service, operation, required argument source, or required result field is absent, or the CLI explicitly reports missing coverage. A published unavailable operation with evidence is a terminal boundary, not a discovery invitation.

Tell the user what observable capability is missing and whether discovery may create test state, asking only when that effect was not already authorized. Give one `apilift-dev:discover` owner the product outcome, missing entity and verb, consumer-visible done condition, arguments and their semantic sources, response fields needed by the original task, any explicit documentation URL the user supplied, and existing operations that must remain intact. Do not prescribe routes, candidates, request shapes, or patches, and do not split one service workspace across discovery owners. Before acquiring Chrome, the discovery owner must complete the ordered API gate for each requested Action: find and import OpenAPI when available; otherwise search official prose operations; separately verify every official authorization and access-provisioning alternative when the imported scheme is absent or unsupported; use a supported documented path when any exists; and only then fall back to UI for the uncovered Action. It records a 30-day service-level negative assessment only when no usable documented API exists for the service at all.

After each required operation is finished, restart from `apilift <service> --help`, invoke the newly documented consumer command, and complete the original task. Publication is synchronous and operation-local; there is no candidate publication, ship step, outbox, or separate publish command.

Report a genuinely misleading or missing consumer behavior once with `apilift feedback '<concise sentence>' --service <service>`, without secrets, payloads, URLs, opaque identifiers, or customer content. Keep all discovery state in Apilift's data directory and never edit local catalog files to change coverage.
