# Overview

URL: https://developers.uidu.org/docs/tools/cli

> The uidu CLI — read a workspace, scaffold an app, and provision content from your terminal or an AI coding agent.

`@uidu/cli` (binary: `uidu`) wraps [`@uidu/client`](https://developers.uidu.org/docs/paths/public-website.md) in a
command-line tool. It's built to be driven by **humans and AI coding agents** (e.g. Claude
Code) alike: read a workspace, scaffold a new project, and provision content — all with
machine-readable `--json` output.

```bash
uidu login                         # browser sign-in (OAuth + PKCE)
uidu stories list --json           # read
uidu events create --name "Launch" # write (needs a Bearer token)
uidu create my-app -t events       # scaffold
```

## Reads vs writes — where each runs

The CLI and the client share one rule, because they share one engine:

| Operation                  | Auth                     | Where it can run                            |
| -------------------------- | ------------------------ | ------------------------------------------- |
| **Reads** (`list` / `get`) | public token             | anywhere — CLI, server, **and the browser** |
| **Writes** (`create`)      | account **Bearer** token | CLI and **server-side** frontend only       |

<Callout type="warn" title="Never ship the account token to the browser">
  Authoring (`create…`) authenticates as your account via a Bearer token. Keep it server-side —
  the CLI (`uidu login`), a Next.js server action, a route handler, or an RSC. The same write
  functions live in `@uidu/client`, so anything you can do from the CLI you can do from your
  backend; just never expose the Bearer token in a client component.
</Callout>

## Install

The CLI ships with the SDK. Run it with your package manager's `dlx`/`npx`, or install it
globally:

```bash
npx @uidu/cli --help
# or
npm install -g @uidu/cli
```

## Configuration

Every command resolves connection + auth in this order: &#x2A;*CLI flags → environment
(`UIDU_*`) → `~/.uidu/config.json`** (written by `uidu login`).

| Env                 | Purpose                                          |
| ------------------- | ------------------------------------------------ |
| `UIDU_WORKSPACE`    | Workspace slug (required)                        |
| `UIDU_PUBLIC_TOKEN` | Read-only token (safe to expose)                 |
| `UIDU_API_KEY`      | Account Bearer token for authoring (server-only) |
| `UIDU_PROJECT_ID`   | Default project for CMS reads                    |
| `UIDU_ENDPOINT`     | Override the GraphQL endpoint                    |

Continue with [Login →](https://developers.uidu.org/docs/tools/cli/login.md) or the [Command reference →](https://developers.uidu.org/docs/tools/cli/commands.md).