Grida CLI

Status: accepted doctrine. Account infrastructure comes first; command and media delivery follows. Examples describe the replacement CLI and are not available in the legacy npm release. See the account infrastructure spec.

Sign in, inspect your account, use a Grida tool, and keep the result in your own workflow. Type the commands yourself, put them in a script, or give them to your preferred agent harness. The command means the same thing in each case.

Start with independent account access

The intended account experience is:

grida auth login
grida account view
grida account credits --org studio

Desktop and CLI are clients of the same capability owners. Exporting a feature means exposing its operation, inputs, permissions, and results through another interface. It does not require Desktop to be running or automate its UI.

The account infrastructure establishes independent login, organization membership, cached credits and scoped GG access. CLI commands and media execution follow separately. Agent and render commands, Canvas integration, subscription billing and MCP remain deferred.

The credential custody study compares established CLIs and defines durable login storage and refresh coordination.

One name, independent products

grida is the branded entry point. Its command tree organizes what you can do; it does not determine where a product's implementation belongs. Account services and media tools retain independent owners, reusable by Desktop and other clients. The CLI translates arguments into their operations and presents the results.

Command depth does not determine package ownership.

Products can arrive or retire independently. Removing a command removes its adapter and distribution dependency; its capability owner stays intact. A public command's removal is still an explicit compatibility change in a release.

Layer	Responsibility
Branded CLI	Command composition, argument parsing, help, terminal output, and exit behavior.
Shared access foundations	Account sessions, credential storage, organization context, and service transport.
Capability owner	Its operations, domain validation, data contracts, and lifecycle.
Command adapter	A small mapping from the command vocabulary to its owner's operations.

Adapters depend on capability owners; owners never import the branded CLI. Other clients can reuse the access foundations and domain data contracts.

Compose built-in commands explicitly. No plugin system or package per verb is needed. Unrelated commands must not initialize a renderer or agent runtime.

Local first

Install a local executable and use it with Desktop closed. Desktop may later offer another installation path; distribution and process lifetime are separate choices.

Local tools use local inputs. Hosted operations make explicit service requests. Account reads and hosted AI generation need a connection. Help and a minimal documentation index work offline; full guides have one canonical hosted home. Unavailable services produce honest errors.

Introduce a persistent service only for operations needing shared or long-lived state. grida account view must not start an agent, launch Desktop, or leave a background server behind.

Ordinary commands, ordinary data

Each command names an operation. Human output explains its result; structured output makes the same result scriptable. Inputs, files, errors, and side effects are documented contracts.

Your harness learns Grida through help, docs, and skills teaching these commands. An AI service can be a capability; the CLI itself has no model, prompt loop, or dependency on Grida's agent runtime.

File operations preserve their format's public contract. Each capability owns its file semantics; the branded CLI defines no private format or canvas model.

Deferred: MCP over the same operations

The CLI is the canonical public command contract. Establish it before MCP; capability owners remain the source of truth for underlying behavior.

MCP may call shared operations or the CLI's structured interface. It preserves authorization, validation, side effects, and result meaning. It never parses human terminal output or duplicates product behavior.

The intended outcomes are:

• Your own harness uses grida and Grida skills.
• Your own harness connects to a local Grida MCP server.
• A cloud client can eventually use a remotely hosted Grida MCP server.

Local MCP follows the CLI. Remote MCP infrastructure is deferred.

Deferred: agent, render, and other products

The overall design can accommodate grida agent and grida render figma. Neither is part of the immediate work or a dependency of account and AI tools. Reusing media execution currently housed beside the agent requires independent capability ownership; it does not bring the agent runtime into the CLI.

If added, Refig and grida-agent retain their own implementations and standalone entry points. Their command details can be designed when those products enter scope. The same boundary applies to future Library or Canvas capabilities.