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 command-line interface (CLI) is the primary tool for developers working with ACI. It handles local development, content validation, preview, and publishing.
Installation
# Install via curl (recommended)
curl -fsSL https://raw.githubusercontent.com/gradial/aci-learn/main/install.sh | sh
# This installs to ~/.local/bin/aci
# Make sure ~/.local/bin is in your PATH
Global Flags
These flags work with any command:
| Flag | Description |
|---|
-s, --site-dir | Site directory containing .aci.yaml (default: current directory) |
-d, --domain | Override the site domain |
-v, --verbose | Enable verbose output |
-h, --help | Help for any command |
Local Development
aci serve
Start a local ACI API server with in-memory storage. This is the foundation for local development — it provides the same API that runs in production, but stores everything locally.
Output:
serving memory API on :8080
| Flag | Description | Default |
|---|
--addr | API listen address | :8080 |
--tenant-id | Tenant ID for the memory API | local |
--repo-id | Repository ID | site-local |
--local-ssg-root | Local SSG hosting artifact root | |
# Terminal 1: Start the API server
aci serve
# Terminal 2: Run your framework dev server
cd packages/astro
npm run dev
aci dev
Start your framework’s development server with ACI integration.
Flags:
| Flag | Description |
|---|
--port | Dev server port override |
- Compiles the component and layout registries
- Starts your framework’s native dev server (e.g.,
astro dev)
- Watches for changes
Requires the component registry to be properly configured. Run aci doctor first to check your setup.
aci doctor
Check your local site configuration and tooling.
Output:
ok: config discovered (.aci.yaml)
ok: version is 1
ok: siteId present (site_aci_local_astro_starter)
ok: framework valid (astro)
ok: component registry exists (src/cms/components.ts)
ok: layout registry exists (src/cms/layouts.ts)
ok: renderer entry exists (src/cms/renderer.ts)
ok: node available
ok: npm available
- Config file exists and is valid
- Required files are present
- Node.js and npm are available
- Registry files can be compiled
Content Management
aci validate
Validate local content files against the component schemas.
Checks all content in .content/ against the schemas defined in your component registry. Reports validation errors with file paths and field names.
aci content status
Show the status of local content files.
aci content pull
Pull content from the API into your local .content/ directory.
aci content push
Push local content changes to the API.
aci content clone
Clone content from the API into a local workspace.
Preview & Render
aci preview
Open a rendered preview of your site.
# Preview the homepage
aci preview
# Preview a specific route
aci preview --route /products/widget
| Flag | Description | Default |
|---|
--route | Route to preview | / |
--no-open | Print path without opening browser | |
--no-render | Open existing HTML without re-rendering | |
# Use your framework's native preview server
aci preview framework
aci render
Render pages using your configured renderer.
Validates content and invokes your renderer to produce HTML output.
aci build
Build your frontend site.
Runs your framework’s build command (e.g., astro build).
aci typecheck
Run TypeScript type checking on your site.
Publishing
aci publish local
Publish content and rendered output to a local release.
Packages your content and renderer output into a release that can be served locally.
Registry Compilation
aci compile
Compile component and layout registries to JSON Schema.
Reads your components.ts and layouts.ts files, extracts the Zod schemas, and generates JSON Schema files in .aci/. These schemas are used for content validation.
API Interaction
The aci api commands interact with a running ACI API server (either local via serve or remote).
Common Flags
| Flag | Description | Default |
|---|
--api-url | ACI API base URL | http://localhost:8080 |
--token | API bearer token | dev-user |
aci api content
Read content from the API.
aci api branches
Manage content branches.
aci api previews
Manage preview sessions.
aci api publishes
Manage publish operations.
aci api releases
Activate or roll back releases.
aci api code-builds
Build and inspect code artifacts.
aci api request
Send a raw API request.
aci api request GET /v1/sites
aci api system
Read API system state.
Typical Workflows
Local Development
# 1. Clone the quickstart repo
git clone https://github.com/gradial/aci-learn.git
cd aci-learn
# 2. Install dependencies
npm install
# 3. Check your setup
cd packages/astro
aci doctor
# 4. Start the dev server
npm run dev
# 5. Edit content in .content/ and see changes instantly
Preview Changes
# Start the local API server
aci serve
# In another terminal, preview a page
aci preview --route /products/widget
Validate Before Committing
# Validate all content
aci validate
# Type-check your code
aci typecheck
# Build to catch any issues
aci build
Environment Variables
| Variable | Description |
|---|
ACI_CONTENT_ROOT | Override the content directory path |
ACI_API_URL | Default API URL for api commands |
ACI_TOKEN | Default API token |
Exit Codes
| Code | Meaning |
|---|
0 | Success |
1 | General error |
2 | Validation error (content or config) |
Next: Quickstart →
