> ## 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 > Use the ACI CLI for local development, content branches, promotion, and releases. 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: ```bash theme={null} 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 --`: ```bash theme={null} npm exec -- aci content validate ``` Use the starter's package scripts for routine local work. They keep the command and SDK version aligned: ```bash theme={null} npm run dev npm run content:compile npm run typecheck npm test npm run build ``` ## Command map ```txt theme={null} 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 --help` for the flags available in your installed SDK. ## Global options | Option | Purpose | | - | - | | `-s, --site-dir ` | Use the project containing the specified `.aci.yaml` | | `-d, --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: ```bash theme={null} 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: ```bash theme={null} npx @gradial/aci init my-site --template astro-starter --with-starter-content ``` Create a Next.js site without sample pages or components: ```bash theme={null} npx @gradial/aci init my-site --template next-starter ``` List the templates provided by the installed package: ```bash theme={null} 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: ```bash theme={null} aci dev ``` Override the framework's development port when needed: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} aci content compile ``` ### `aci content validate` Validate content structure and, when run inside a configured site, component prop schemas: ```bash theme={null} aci content validate ``` Use an explicit source directory outside a configured project: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} aci content diff --branch campaign-refresh ``` ### `aci content push` Preview the changes that would be sent to a content branch: ```bash theme={null} aci content push --branch campaign-refresh --dry-run ``` After reviewing the plan, push the changes: ```bash theme={null} 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: ```bash theme={null} 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 ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} aci code-build --branch campaign-refresh --folder apps/marketing ``` ## Promote approved content Landing and publishing are separate operations: ```mermaid theme={null} flowchart LR A["Working branch"] -->|"review and land"| B["main: approved"] B -->|"promote selected paths"| C["live: publishable"] C -->|"stage and activate"| D["Active release"] ``` ### `aci drift` List paths whose approved state on `main` differs from their published state on `live`: ```bash theme={null} aci drift ``` Use this before a promotion to see what is approved but not yet live. ### `aci promote` Preview a path-scoped promotion: ```bash theme={null} aci promote --path /pages/pricing/_index.json --dry-run ``` Promote one or more paths after reviewing the plan: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} aci release status "$RELEASE_ID" ``` ### `aci release activate` After reviewing the preview, activate the staged release with the active state returned by `release publish`: ```bash theme={null} 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: ```bash theme={null} 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. ```bash theme={null} 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 --help` to inspect the file and asset arguments supported by your installed CLI. ## Recommended workflows ### Local frontend change ```bash theme={null} npm run dev npm run content:compile npm run typecheck npm test npm run build ``` ### Content branch ```bash theme={null} 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 ```bash theme={null} 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 →](/aci/architecture/agent-native-design)* This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.