CLI Reference - Gradial Docs

The Gradial ACI (Agentic Content Infrastructure) CLI connects local frontend work to the same content and release workflow used by the hosted product. Use it to scaffold projects, compile and validate content, work on branches, promote approved paths, and manage releases.

Run the CLI

ACI starters install the aci binary through @gradial/aci. Check the project-local version with:

npm exec -- aci --version
npm exec -- aci --help

The examples below use aci for readability. From a project where the binary is not already on your shell path, prefix a command with npm exec --:

npm exec -- aci content validate

Use the starter’s package scripts for routine local work. They keep the command and SDK version aligned:

npm run dev
npm run content:compile
npm run typecheck
npm test
npm run build

Command map

aci
├── init
├── dev
├── validate
├── content
│   ├── pull
│   ├── push
│   ├── compile
│   ├── diff
│   └── validate
├── branch
│   ├── list
│   ├── get
│   ├── create
│   ├── delete
│   ├── changes
│   ├── patch
│   ├── rebase
│   ├── refresh-code
│   └── land
├── code-build
├── promote
├── drift
├── release
│   ├── publish
│   ├── activate
│   ├── rollback
│   └── status
└── dam
    ├── upload
    ├── upload-version
    └── download

Run aci <command> --help for the flags available in your installed SDK.

Global options

Option	Purpose
`-s, --site-dir <path>`	Use the project containing the specified `.aci.yaml`
`-d, --domain <domain>`	Override the configured site domain
`-v, --verbose`	Show additional command output
`-h, --help`	Show command help
`--version`	Show the installed CLI version

Hosted commands use your organization’s ACI API URL and access token. Set them in the environment to avoid placing credentials in shell history:

export ACI_API_URL="https://your-tenant-api.example"
export ACI_API_TOKEN="your-access-token"

Your Gradial team provides the correct API URL and access method for each environment. Do not commit tokens to the repository.

Create a project

`aci init`

Create an Astro site with sample content:

npx @gradial/aci init my-site --template astro-starter --with-starter-content

Create a Next.js site without sample pages or components:

npx @gradial/aci init my-site --template next-starter

List the templates provided by the installed package:

npx @gradial/aci init --list

Astro is the standard starter for a new site. --with-starter-content adds sample content, components, assets, and stories; without it, the project starts with empty registries and the required integration structure.

Develop locally

`aci dev`

Compile local content, watch it for changes, and run the configured framework development server:

aci dev

Override the framework’s development port when needed:

aci dev --port 4400

The generated npm run dev script is the usual entrypoint for a starter project.

Work with content

`aci content compile`

Compile authored content into the generated local output:

aci content compile --content ./.content --out ./.aci/compiled

If you run the command from the site root, the CLI can discover these paths from the project configuration:

aci content compile

`aci content validate`

Validate content structure and, when run inside a configured site, component prop schemas:

aci content validate

Use an explicit source directory outside a configured project:

aci content validate --content ./content-export

Running from the site root performs the most complete check because the CLI can load the component and layout contracts.

`aci validate`

Validate the coherence of the complete content snapshot for the configured site. Every content document is parsed and checked against the project’s contracts, and referenced assets are resolved:

aci validate

The command exits non-zero when errors are found, which makes it suitable for CI gates. Use --format json for machine-readable output.

`aci content pull`

Pull a branch’s content into the local content directory:

aci content pull --branch campaign-refresh

Pull replaces the local runtime content tree with the selected remote branch. Commit, stash, or otherwise preserve local edits before you run it.

`aci content diff`

Compare local content with a remote branch before pushing:

aci content diff --branch campaign-refresh

`aci content push`

Preview the changes that would be sent to a content branch:

aci content push --branch campaign-refresh --dry-run

After reviewing the plan, push the changes:

aci content push --branch campaign-refresh

Use --files for a targeted initial seed or update. Repeat the option as needed and review a dry run first:

aci content push \
  --branch campaign-refresh \
  --files .content/pages/campaign \
  --dry-run

Work with branches

ACI branches isolate content and its linked code while work is in progress. Landing a reviewed branch updates main, the approved content trunk. It does not put the change live.

Inspect and create branches

aci branch list
aci branch get campaign-refresh
aci branch create campaign-refresh --source-ref main

Rebase and land

Read the branch and target state first, then pass the observed heads when you rebase or land. These checks prevent an update from silently overwriting newer work.

aci branch rebase campaign-refresh \
  --target-ref main \
  --expected-head "$BRANCH_HEAD" \
  --expected-target-head "$MAIN_HEAD"

aci branch land campaign-refresh \
  --target-ref main \
  --expected-head "$REBASED_BRANCH_HEAD" \
  --expected-target-head "$CURRENT_MAIN_HEAD"

Other branch operations

Command	Use
`aci branch changes NAME`	Apply an explicit multi-file JSON change set with an expected branch head
`aci branch patch NAME PATH`	Apply an RFC 6902 patch to one content file
`aci branch refresh-code NAME`	Refresh a branch’s linked code and layouts from another ref
`aci branch delete NAME`	Close a branch when it is no longer needed

For normal local authoring, content pull, file edits, content diff, and content push provide the clearest workflow. Use changes and patch for structured integrations that already manage branch concurrency.

Build code for a branch

`aci code-build`

Build the current Git state and link the resulting code to a non-main content branch:

aci code-build --branch campaign-refresh

Run this after a component, contract, layout, or other frontend code change that the branch needs for preview. The source repository must already be connected and accessible to your ACI environment. For a site inside a monorepo, use --folder if the CLI cannot infer the site directory:

aci code-build --branch campaign-refresh --folder apps/marketing

Promote approved content

Landing and publishing are separate operations:

`aci drift`

List paths whose approved state on main differs from their published state on live:

aci drift

Use this before a promotion to see what is approved but not yet live.

`aci promote`

Preview a path-scoped promotion:

aci promote --path /pages/pricing/_index.json --dry-run

Promote one or more paths after reviewing the plan:

aci promote \
  --path /pages/pricing/_index.json \
  --path /fragments/pricing-cta/_index.json \
  --note "Publish approved pricing update" \
  --yes

The CLI always evaluates the plan first. It reports conflicts and warns when the selected files were approved together with paths you did not select. --yes is required to apply the promotion.

Stage and activate releases

Promotion updates the publishable content state. Release commands build that state into an immutable release, give you a preview to review, and then make the approved release live.

`aci release publish`

Stage a release:

aci release publish

The command returns the new release ID and preview URL. It also reports the currently active release and its generation; keep those values for activation. Pass --activate to stage and activate in one step. Keep the steps separate when the release needs review at its preview URL before activation.

`aci release status`

Check a staged release:

aci release status "$RELEASE_ID"

`aci release activate`

After reviewing the preview, activate the staged release with the active state returned by release publish:

aci release activate "$RELEASE_ID" \
  --expected-release "$CURRENT_RELEASE_ID" \
  --expected-generation "$CURRENT_GENERATION"

On the first activation, the returned current release may be empty. Pass the value exactly as returned, including --expected-release "" when it is empty.

`aci release rollback`

Switch the whole site back to a previous release:

aci release rollback "$PREVIOUS_RELEASE_ID" \
  --expected-release "$CURRENT_RELEASE_ID" \
  --expected-generation "$CURRENT_GENERATION"

The expected release and generation protect both activation and rollback from racing with another release change. Refresh the active state and retry if either value is stale.

Use aci promote with an older source when you need to roll back selected content paths. Use aci release rollback when you need to switch the complete site to an earlier release.

Manage asset binaries

The dam commands move asset binaries. Asset metadata remains part of the content tree and follows the normal branch workflow.

aci dam upload ./hero.jpg --folder /campaigns/summer
aci dam upload-version "$ASSET_ID" ./hero-v2.jpg
aci dam download "$ASSET_ID" --out ./hero.jpg

Use aci dam <command> --help to inspect the file and asset arguments supported by your installed CLI.

Recommended workflows

Local frontend change

npm run dev
npm run content:compile
npm run typecheck
npm test
npm run build

Content branch

aci branch create campaign-refresh --source-ref main
aci content pull --branch campaign-refresh
# Edit .content files.
aci content validate
aci content diff --branch campaign-refresh
aci content push --branch campaign-refresh --dry-run
aci content push --branch campaign-refresh

Approved change to production

aci drift
aci promote --path /pages/pricing/_index.json --dry-run
aci promote --path /pages/pricing/_index.json --yes
aci release publish
# Review the returned preview URL.
aci release activate "$RELEASE_ID" \
  --expected-release "$CURRENT_RELEASE_ID" \
  --expected-generation "$CURRENT_GENERATION"

Next: Agent-ready projects →

​Run the CLI

​Command map

​Global options

​Create a project

​aci init

​Develop locally

​aci dev

​Work with content

​aci content compile

​aci content validate

​aci validate

​aci content pull

​aci content diff

​aci content push

​Work with branches

​Inspect and create branches

​Rebase and land

​Other branch operations

​Build code for a branch

​aci code-build

​Promote approved content

​aci drift

​aci promote

​Stage and activate releases

​aci release publish

​aci release status

​aci release activate

​aci release rollback

​Manage asset binaries

​Recommended workflows

​Local frontend change

​Content branch

​Approved change to production

Run the CLI

Command map

Global options

Create a project

`aci init`

Develop locally

`aci dev`

Work with content

`aci content compile`

`aci content validate`

`aci validate`

`aci content pull`

`aci content diff`

`aci content push`

Work with branches

Inspect and create branches

Rebase and land

Other branch operations

Build code for a branch

`aci code-build`

Promote approved content

`aci drift`

`aci promote`

Stage and activate releases

`aci release publish`

`aci release status`

`aci release activate`

`aci release rollback`

Manage asset binaries

Recommended workflows

Local frontend change

Content branch

Approved change to production