> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> The aci CLI: commands for local site development, content sync, branches, DAM binaries, and validation.

The `aci` command-line interface is the developer entrypoint for ACI sites. It validates the frontend contract, compiles content, runs framework development servers, syncs content, and calls branch and DAM APIs.

## Installation

Design partner starters install `@gradial/aci` as a project dependency. Use the starter scripts first:

```bash theme={null}
npm run aci:doctor
npm run aci:validate
```

You can also invoke the local CLI directly:

```bash theme={null}
npx aci --help
npx aci --version
```

## Global Flags

| Flag             | Description                           |
| ---------------- | ------------------------------------- |
| `-s, --site-dir` | Site directory containing `.aci.yaml` |
| `-d, --domain`   | Site domain override                  |
| `-v, --verbose`  | Enable verbose output                 |
| `-h, --help`     | Help for any command                  |
| `--version`      | Print CLI version                     |

## Commands

```txt theme={null}
aci
├── build
├── dev
├── doctor
├── content
│   ├── clone
│   ├── pull
│   └── push
├── branch
│   ├── list
│   ├── get
│   ├── create
│   ├── delete
│   ├── changes
│   ├── patch
│   ├── link-code
│   ├── rebase
│   └── land
└── dam
    ├── upload
    ├── upload-version
    └── download
```

## Local Development

### `aci doctor`

Checks local site configuration and tooling.

```bash theme={null}
aci doctor
```

It checks:

* `.aci.yaml` is discovered and valid
* `version`, `siteId`, and `framework` are valid
* Component registry, layout registry, and renderer entry exist
* The renderer exports a `GradialRenderer`
* Node.js and npm are available
* Framework-specific requirements, such as Next.js catch-all routes, are present
* `.aci/registry.json` can be compiled and loaded

### `aci build`

Compiles content and builds the configured framework site.

```bash theme={null}
aci build
```

Flags:

| Flag              | Description                                             |
| ----------------- | ------------------------------------------------------- |
| `--compile-only`  | Only compile component/layout registries to JSON Schema |
| `--validate-only` | Only validate local content against schemas             |
| `--content <dir>` | Source content directory                                |
| `--out <dir>`     | Compiled content output directory                       |
| `--skip-code`     | Skip the framework build after content compilation      |
| `--skip-content`  | Skip content compilation before the framework build     |

Common starter scripts:

```bash theme={null}
# Compile contract registry into .aci/
aci build --compile-only

# Compile .content into .aci/compiled without running the framework build
aci build --skip-code --content ./.content --out ./.aci/compiled

# Compile content and run npm run build for the framework site
aci build --content ./.content
```

### `aci dev`

Runs the configured framework development server with ACI content environment variables.

```bash theme={null}
aci dev
```

Flags:

| Flag               | Description                                    |
| ------------------ | ---------------------------------------------- |
| `--port <port>`    | Framework dev server port override             |
| `--ws-port <port>` | Dev refresh websocket port; set `0` to disable |

`aci dev` compiles registries if needed, sets `ACI_CONTENT_ROOT`, starts a local `/aci-dev` websocket for content refresh notifications, and then runs the framework's `npm run dev`.

## Content Commands

### `aci content pull`

Pulls content from the hosted API or directly from S3 into a local content directory.

```bash theme={null}
# API mode
aci content pull --api-url https://api.example.com --token "$ACI_API_TOKEN" --branch main --out .content

# S3 direct mode
aci content pull --s3-bucket my-bucket --s3-region us-east-1 --repo-id site-123 --branch main --out .content
```

Flags:

| Flag                   | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| `--out <dir>`          | Output directory; defaults from config or `.content` |
| `--branch <name>`      | Content branch to pull; defaults to `main`           |
| `--force`              | Overwrite an existing content directory              |
| `--api-url <url>`      | ACI API base URL                                     |
| `--token <token>`      | API bearer token                                     |
| `--s3-bucket <bucket>` | Enables S3 direct mode                               |
| `--s3-region <region>` | S3 region                                            |
| `--s3-endpoint <url>`  | S3-compatible endpoint, such as MinIO                |
| `--repo-id <id>`       | Repository ID for S3 mode                            |

### `aci content clone`

Clones a path-scoped API content workspace.

```bash theme={null}
aci content clone agent-home-refresh ./workspace-home \
  --path /pages/home/_index.json \
  --target-ref main
```

Use this when an agent or developer should work on a focused subset of content files. `--path` is required and can be repeated.

### `aci content push`

Pushes local content workspace changes through the API.

```bash theme={null}
aci content push ./workspace-home
```

## Branch Commands

Branch commands call the ACI API. They default to `http://localhost:8080` and token `dev-user`, or you can pass `--api-url` and `--token`.

### `aci branch list`

```bash theme={null}
aci branch list --api-url http://localhost:8080
```

### `aci branch create`

```bash theme={null}
aci branch create agent-seo-optimization --source-ref main
```

### `aci branch get`

```bash theme={null}
aci branch get agent-seo-optimization
```

### `aci branch changes`

Applies explicit JSON changes to a branch.

```bash theme={null}
aci branch changes agent-seo-optimization \
  --if-match <expected-head> \
  --body-file ./changes.json
```

### `aci branch patch`

Applies an RFC 6902 JSON patch to one content file.

```bash theme={null}
aci branch patch agent-seo-optimization /pages/home/_index.json \
  --if-match <expected-head> \
  --op replace \
  --pointer /metadata/title \
  --value '"New title"'
```

### `aci branch link-code`

Patches `/config/site.json` to point at a code artifact.

```bash theme={null}
aci branch link-code main build-2026-06-18 sha256:abc123 \
  --if-match <expected-head> \
  --source-repo-url https://github.com/example/site \
  --source-commit <git-sha>
```

### `aci branch rebase`

```bash theme={null}
aci branch rebase agent-seo-optimization --target-ref main --expected-head <head>
```

### `aci branch land`

Squash-lands a branch into the target branch.

```bash theme={null}
aci branch land agent-seo-optimization --target-ref main --expected-head <head>
```

## DAM Commands

DAM commands call the ACI API and use the signed upload/download flow.

### `aci dam upload`

Uploads a new DAM asset binary.

```bash theme={null}
aci dam upload ./hero.jpg --folder /campaigns/summer
```

Metadata is edited through commit-engine files; the upload command only handles binaries.

### `aci dam upload-version`

Uploads a new immutable binary version for an existing asset.

```bash theme={null}
aci dam upload-version ast_site_home_hero ./hero-v2.jpg
```

### `aci dam download`

Downloads a DAM asset original.

```bash theme={null}
aci dam download ast_site_home_hero --out ./hero.jpg
```

## Environment Variables

| Variable                    | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| `ACI_API_URL`               | Default API URL for API-backed content, branch, and DAM commands |
| `ACI_API_TOKEN`             | Default API bearer token                                         |
| `ACI_DEV_WS_PORT`           | Dev refresh websocket port; set `0` to disable                   |
| `ACI_DISABLE_CONTENT_WATCH` | Set to `1` to disable local content watch broadcasts             |
| `ACI_S3_BUCKET`             | Default S3 bucket for direct content pull                        |
| `ACI_S3_REGION`             | Default S3 region for direct content pull                        |
| `ACI_S3_ENDPOINT`           | S3-compatible endpoint for direct content pull                   |
| `ACI_REPO_ID`               | Repository ID for S3 direct content pull                         |
| `AWS_ACCESS_KEY_ID`         | S3 access key for direct content pull                            |
| `AWS_SECRET_ACCESS_KEY`     | S3 secret key for direct content pull                            |

## Typical Workflows

### Local Starter Development

```bash theme={null}
npm install
npm run aci:doctor
npm run aci:compile
npm run aci:validate
npm run build
npm run dev
```

### Validate Before Commit

```bash theme={null}
npm run aci:doctor
npm run aci:compile
npm run aci:validate
npm run typecheck
npm run build
```

### API Content Workspace

```bash theme={null}
aci branch create agent-home-refresh --source-ref main
aci content clone agent-home-refresh ./workspace-home --path /pages/home/_index.json
# edit files in ./workspace-home
aci content push ./workspace-home
aci branch rebase agent-home-refresh --target-ref main --expected-head <head>
aci branch land agent-home-refresh --target-ref main --expected-head <head>
```

***

*Next: [Quickstart →](/aci/developers/quickstart)*