Entity Auth CLI

What is it?

The Entity Auth CLI lets AI agents and developers interact with Entity Auth through a single, discoverable capability graph. Running one command emits the full set of available actions, so an AI agent never needs to guess follow‑ups.

LLM‑first flow

Run the init command once. The CLI prints the full capability graph and usage templates. Agents can then choose exactly what to run next without asking for help.

One command to expose the graph

npx @entityauth/cli@latest init entity-auth

What you get back:

A JSON graph of all available nodes (capabilities):
- Docs — content articles you can read programmatically
- Components — UI components you can install into your app
- Setup — app templates you can scaffold end‑to‑end
A command_shapes section that shows the exact command templates to run each capability

Agents can parse this output and proceed end‑to‑end with no additional discovery commands.

Capabilities

Read product docs

# Read any doc by node id from the graph
npx @entityauth/cli docs read entity-auth --node entityauth:docs:quickstart

Use this to pull structured content (e.g., Quickstart, Authentication, Organizations) directly from the bundled docs.

Install UI components

# Install all components
npx @entityauth/cli ui install entity-auth --mode all

# Or select specific components by name
npx @entityauth/cli ui install entity-auth --mode multiple --names auth-form

Components are written into your project with deterministic paths and overwrite‑on‑write semantics.

Scaffold app templates (Setup)

# Scaffold a Next.js + Entity Auth baseline and place files under ./entity-auth
npx @entityauth/cli setup run entity-auth --node entityauth:setup:basic

# Optional: choose a workspace directory
npx @entityauth/cli setup run entity-auth --node entityauth:setup:basic --workspace /path/to/app

Setup nodes can run non‑interactive scaffold commands (like create-next-app) and then copy ready‑to‑use entity-auth/ files (client.ts, provider.tsx, middleware.ts, and components/).

How agents should use it

Emit the graph

Run npx @entityauth/cli@latest init entity-auth and read the JSON. The graph includes all nodes plus command_shapes showing exactly how to invoke each capability.

Pick a node and execute

Choose the relevant node by id (e.g., entityauth:setup:basic) and run the corresponding command template (e.g., setup run ...).

Continue with next visible node

No hidden prerequisites. If inputs are missing, the CLI returns a single JSON error envelope describing required keys.

Stay stateless

The model never needs to ask for help; everything required is visible in the emitted graph.

Examples

# 1) Discover capabilities
npx @entityauth/cli@latest init entity-auth

# 2) Read a doc
npx @entityauth/cli docs read entity-auth --node entityauth:docs:authentication

# 3) Install UI
npx @entityauth/cli ui install entity-auth --mode all

# 4) Scaffold a Next.js template
npx @entityauth/cli setup run entity-auth --node entityauth:setup:basic

Platform support

macOS Apple Silicon (arm64) only for now. The npm package downloads a native binary.
Intel macOS, Windows, and Linux are planned but not yet supported.

Troubleshooting

If postinstall fails: ensure network access and that your environment is darwin/arm64.
If a command returns a JSON error: provide the fields indicated in the error payload and retry once.