CLI Reference - Gradial Docs

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:

npm run aci:doctor
npm run aci:validate

You can also invoke the local CLI directly:

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

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.

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.

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:

# 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.

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.

# 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.

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.

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`

aci branch list --api-url http://localhost:8080

`aci branch create`

aci branch create agent-seo-optimization --source-ref main

`aci branch get`

aci branch get agent-seo-optimization

`aci branch changes`

Applies explicit JSON changes to a branch.

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.

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.

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`

aci branch rebase agent-seo-optimization --target-ref main --expected-head <head>

`aci branch land`

Squash-lands a branch into the target branch.

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.

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.

aci dam upload-version ast_site_home_hero ./hero-v2.jpg

`aci dam download`

Downloads a DAM asset original.

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

npm install
npm run aci:doctor
npm run aci:compile
npm run aci:validate
npm run build
npm run dev

Validate Before Commit

npm run aci:doctor
npm run aci:compile
npm run aci:validate
npm run typecheck
npm run build

API Content Workspace

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 →

​Installation

​Global Flags

​Commands

​Local Development

​aci doctor

​aci build

​aci dev

​Content Commands

​aci content pull

​aci content clone

​aci content push

​Branch Commands

​aci branch list

​aci branch create

​aci branch get

​aci branch changes

​aci branch patch

​aci branch link-code

​aci branch rebase

​aci branch land

​DAM Commands

​aci dam upload

​aci dam upload-version

​aci dam download

​Environment Variables

​Typical Workflows

​Local Starter Development

​Validate Before Commit

​API Content Workspace

Installation

Global Flags

Commands

Local Development

`aci doctor`

`aci build`

`aci dev`

Content Commands

`aci content pull`

`aci content clone`

`aci content push`

Branch Commands

`aci branch list`

`aci branch create`

`aci branch get`

`aci branch changes`

`aci branch patch`

`aci branch link-code`

`aci branch rebase`

`aci branch land`

DAM Commands

`aci dam upload`

`aci dam upload-version`

`aci dam download`

Environment Variables

Typical Workflows

Local Starter Development

Validate Before Commit

API Content Workspace