Grida CLI v1

Status: accepted command contract for the CLI preview. Immediate is the first-release scope; planned has no release commitment. See the doctrine for product boundaries.

Scope: account infrastructure and AI tools

Use the account services and AI capabilities available to Grida Desktop from your terminal or your own harness. The CLI runs independently; Desktop and CLI share capability owners, account permissions, and execution contracts.

Immediate	What ships
Account infrastructure	Login, session storage, identity, organization membership, and cached credits.
AI tools	Model discovery and schemas, GG/BYOK availability, provider credentials, and existing media generation operations with local output files.
CLI foundations	Standalone installation, help/docs, structured results, and predictable failures.

Agent and render commands, Canvas integration, and MCP are deferred. The first release exports existing capabilities; broader provider access and new product features are separate extensions.

Immediate: install and sign in

The intended first session is:

npm install -g grida@next
grida auth login
grida account view
grida account credits --org studio
grida models list --provider gg --org studio --available
grida models inspect --provider gg --model openai/gpt-image-2 --json
grida generate --provider gg --model openai/gpt-image-2 \
  --org studio --prompt "A blue ceramic teapot" --out ./images

The legacy npm release does not provide these commands. V1 installs independently and runs with Desktop closed. Commands exit when finished; login's temporary callback listener is the only local server needed.

Command	What you get
grida auth login	Sign in to your Grida account in the system browser and save a CLI session.
grida auth status	Inspect the locally saved account and session state without displaying credentials. This does not verify the session with the server.
grida auth logout	Remove this CLI's local credentials and request revocation of its session. Report whether remote revocation succeeded.
grida account view	Your current account ID, email, display name, and organizations you belong to.
grida account credits --org studio	The organization's cached credit estimate and cached billing eligibility.
grida docs [command...]	Print the canonical documentation URL for the command.

Use grida --help, grida --version, or --help on any command without logging in. grida without arguments displays help.

Immediate: account access

Save one Grida account on this machine. The CLI is a registered first-party public OAuth application: its client ID identifies the application, not a trusted installation, and it contains no client secret. Login uses the system browser, authorization code with PKCE, and a temporary listener on an exact registered loopback address. If its registered ports are occupied, login fails before opening the browser. Desktop's cookies are not a credential source. auth login --no-browser prints the sign-in URL for manual opening on the same machine; the browser ceremony and loopback callback are still required.

Browser sign-in authorizes a separate CLI session. Logout revokes that session; revoking the application's grant affects its sessions across installations. Account-wide sign-out can also invalidate CLI sessions. Identity scopes do not reduce existing account or organization permissions.

Credential storage is restricted to the current OS user. The credential custody contract covers backend selection and coordination between concurrent commands. New profiles use the OS keyring; auth login --storage file explicitly selects file storage. Inspect with auth storage show and change an existing profile with auth storage migrate <keyring|file>. An unavailable backend never causes an automatic switch. Commands refresh expired access when possible, otherwise instruct you to run grida auth login. Account reads never start login themselves. Logout clears local credentials even offline and reports any unconfirmed remote revocation. Already signed out locally is a successful no-op.

All account reads require login and a connection. account view lists your memberships, including an empty list. Credits are organization-scoped: select one with --org <slug> or --org-id <id>. These flags are mutually exclusive; a numeric slug remains a slug. Omit both only if you belong to exactly one organization; otherwise the error lists the choices. Results identify the organization. Browser selections never supply this default.

Immediate: know what you have

Reads use existing authorities and never provision a billing account, purchase credit, or alter a subscription.

Credits return the organization, billing-account presence, provisioning/cache state, a nullable balance in USD cents, the cache update time, and the cached billing gate's eligibility and blocked reason. Reads use the existing cache; they do not contact a provider or refresh the balance.

An absent billing account, unprovisioned credits, an unobserved cache and a recorded zero remain distinguishable. Balances are approximate. The timestamp records a cache update, which may include estimated usage deductions; it does not promise a recent provider reconciliation. An aggregate balance has no single expiry date. Cached eligibility does not guarantee a generation request will succeed; generation checks its own current access and availability.

These reads require organization membership. Subscription plans/status, invoices, payment methods and billing mutations are deferred. The billing WG owns the billing model.

Immediate: discover and use AI tools

Keep models and generate at the root, without an ai family. Discover by modality; invoke an operation with its own input/output schema.

Command	What you get
grida models list --modality image	Bundled executable operations; no access check by default.
grida models list --modality video --local-image	Operations accepting a local image, derived from their input schemas.
grida models inspect --provider gg --model <id>	Effective JSON input schema and native output description.
grida providers list	Key presence and effective source without displaying keys.
grida voices list --provider elevenlabs	Provider speech voices using the selected credential.
grida generate --provider <provider> --model <id> --input @request.json --out ./result	Generate, wait and save artifacts into a new directory with a receipt.

Export existing image, video, audio, and 3D operations through independently usable adapters. Music, speech, and sound effects keep their distinct contracts; speech includes voice discovery. Expose only what the selected executor actually supports; catalogue entries and upstream provider capabilities do not establish CLI support. The AI tools design owns the schema, availability, and artifact rules.

GG requires Grida login, an organization, and credit eligibility. Independent CLI sessions must be able to obtain scoped GG access. BYOK uses the selected provider's shared stored key, environment variable or --key-stdin, without Grida login. grida providers configure <provider> saves a key using hidden input or --key-stdin; grida providers remove <provider> removes it for both Desktop and CLI. Keys are never literal arguments. The custody contract owns plaintext TOML protection, override precedence, static key validation, configuration-time provider checks and Desktop migration. Grida logout leaves provider keys intact.

Choose --provider explicitly. A failed request never switches provider or billing route. --input - accepts JSON from stdin. Generation saves the same files with or without --json, retains a receipt, and distinguishes provider failure from a failed local save. It never silently retries a possibly accepted paid submission. Detached jobs and general status/cancel commands are planned.

Immediate: useful in a terminal or a script

grida docs
grida docs account credits
grida docs generate
grida account credits --org studio --json

Installed help explains the available syntax. docs prints a URL to the canonical documentation home, without opening a browser or fetching content. Help and printing links work offline; reading the linked documentation needs a connection. Guides and examples live in one place, with no bundled copy or documentation search service in v1.

--no-input prevents terminal interaction; commands needing it fail with a useful error. It does not prevent OS keyring access dialogs. Interactive login rejects --json and --no-input. Account reads, auth status, provider listing, model discovery, and generation support --json: no prompts, one result, stable fields, explicit nulls, and stable error codes/messages. Diagnostics go to stderr; stdout holds the result. Credentials never enter output or logs.

Exit codes: 0 success, 1 operation failure, 2 invalid usage. Signed-out auth status returns 1. Logout returns 1 when an existing session was removed locally but remote revocation failed.

Immediate: infrastructure before CLI features

Delivery has two dependency phases, each spanning coherent PRs. Establish reusable infrastructure first, starting with auth; build the supported command experience over it next. A native auth probe can verify infrastructure before the CLI exists.

1. Independent account login. Browser authorization, CLI callback, protected local session storage, refresh, and session revocation. Account login and local daemon credentials remain separate contracts.
2. Independent-client read APIs. Identity and memberships, then passive credit summaries. Billing management is deferred. Browser routes and scoped GG tokens do not supply this contract; preserve existing authorities and permissions.
3. AI capabilities shared with Desktop. Give media execution independent owners, publish effective schemas, and expose the same GG/BYOK operations without loading the agent runtime. Add CLI-scoped GG access, explicit provider credential inputs, and local artifact saving.
4. CLI composition and distribution. Publishable grida wrapper, command adapters, shared output rules, and local help. Resolve the workspace name overlap and legacy install guidance before release.
5. Release verification. Install the packed artifact; prove login → account → models → generation → saved files → logout with Desktop closed. Use local auth, sandbox billing, and controlled provider fixtures; check both GG and BYOK, unavailable routes, offline help/docs links, org ambiguity, and JSON failures.

A GG image operation and an existing BYOK operation establish the first complete path. Extend that path across existing video, audio, and 3D operations; these are part of the immediate AI tools work, not a separate agent milestone.

Installed-client compatibility

An installed CLI or Desktop release outlives a web deployment. The command interface, structured results and errors, account API, OAuth registration, callback addresses and credential formats are versioned contracts. Changing a server deployment does not upgrade its clients.

Additive optional fields may extend a contract. Removing or renaming fields, requiring new inputs, changing authority or invalidating existing callbacks requires an explicit migration and release note. Before the first public release, preview contracts may change together; public release begins the obligation to support the installed versions named in release documentation. Human-readable formatting is not a scripting contract; JSON output is.

Deploy compatible server additions first, then release clients that use them. Remove an old contract only after an announced retirement and a migration for every supported consumer, including Desktop. Keep compatibility handlers with their domain owner; an old route with live consumers is not dead code.

Provider model availability is external and can change independently. The CLI must report an unavailable operation honestly, preserving the selected provider and billing route. It must never turn a model retirement into an automatic paid fallback. Discovery describes the capabilities of the installed CLI version.

Every release validates its packaged executable, documentation and service contracts at the same source revision. Restoring a previous distribution tag does not replace binaries already installed: an urgent fix needs a new version and compatible server behavior. Withdrawing an affected version from new installs must preserve users' ability to understand and migrate from it.

Planned: extend the AI tools

• Optional provider keyring storage and Windows ACL support; see the custody contract.
• Provider-native endpoints outside Grida's catalogue, starting with fal JSON queue operations and explicit raw input; see the provider-native design.
• Detached generation and status/result/cancel where an adapter supports them.
• Additional operations, providers, and modality convenience commands beyond the initial Desktop capability export.

Deferred: other products and integrations

Surface	Proposed direction
Subscription billing	Consider plan/status reads separately from the essential credit check used before generation.
grida render figma	Delegate rendering to Refig; keep its implementation and standalone distribution independently owned.
grida agent	Adapt the existing Grida agent runtime. Preserve grida-agent; do not make it a v1 dependency.
Library commands	Add command adapters over the Library owner's operations.
Skills for external harnesses	Teach the public CLI commands without requiring Grida's agent tools.
Local MCP	Expose the same operations; choose server lifetime when this surface is designed.
Desktop installation/integration	Optional distribution and explicit app capabilities, with independent version/lifetime rules.
Headless/CI login and multiple accounts	Add credential provisioning and account selection after the initial interactive login contract.
Remote MCP	Deferred infrastructure work.

Command vocabulary

Use auth login for Grida sign-in, account for profile and credits, and providers for separate BYOK credentials.