Description
This command family gives administrators a complete terminal workflow for establishing identity and governing who can do what inside a Dots company. dots auth and dots use establish the credential and company context, while dots access exposes the live RBAC catalog, principals, roles, assignments, grants, entitlements, credentials, approvals, invitations, and audit records.
The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.
Selling Points
- Keeps access changes scriptable, so onboarding and offboarding do not depend on a browser session.
- Makes the active company explicit before sensitive work, reducing accidental cross-company administration.
- Supports both human and agent principals through the same permission vocabulary and audit trail.
- Provides approval and credential lifecycle commands alongside grants, avoiding fragmented security operations.
- Returns structured output suitable for evidence collection, review, and repeatable governance checks.
User Story
A workspace administrator signs in, selects the intended company, inspects the permission catalog, creates a constrained agent credential, and verifies the resulting assignment and audit record. They leave with a usable credential and a terminal transcript showing exactly which authority was granted. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.
Extension Surface
The surface is automatable: packages/cli/src/commands/auth.ts and packages/cli/src/commands/access.ts bind the closed command vocabulary to API routes, with no third-party registration point for new access verbs. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.
Capabilities & Limits
- Capability: Login, logout, identity inspection, and persistent active-company selection.
- Capability: Role, grant, entitlement, credential, approval, invitation, and principal administration.
- Capability: Machine-readable audit inspection through the standard CLI formatters.
- Limit: The CLI cannot bypass server authority: a caller can only grant or inspect what the authenticated company membership and route guards permit.
The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.
Implementation Map
packages/cli/src/commands/auth.tspackages/cli/src/commands/access.tspackages/cli/src/context.ts