CLI Reference

The @useacms/cli package provides command-line tools for development, deployment, and schema management. All commands are run via acms (or npx acms).

acms dev

Start the local development server.

acms dev
acms dev -p 3002        # Custom port

What it does:

• Starts an Express API server on port 3001 (default)
• Serves the REST API for field registration and content management
• Automatically generates acms.d.ts with TypeScript definitions
• Watches acms.json for changes and regenerates types (300ms debounce)
• Provides Server-Sent Events (SSE) for live dashboard updates
• Tracks field access timestamps in metadata
• Loads environment variables from .env

Options:

Flag	Description	Default
-p, --port <number>	Port for the dev server	3001

acms push

Push your local schema to the production storage adapter.

acms push
acms push --force       # Skip confirmation prompt

Reads acms.json and uploads it to the production adapter defined in acms.config.ts. By default, prompts for confirmation before overwriting remote content.

Options:

Flag	Description
--force	Skip the confirmation prompt

acms pull

Pull schema from the production storage adapter to your local acms.json.

acms pull

Downloads the schema from the production adapter and writes it to acms.json. Overwrites local content with the remote version.

acms sync

Bi-directional sync between local and remote schemas.

acms sync
acms sync --resolve remote    # Use remote values for conflicts
acms sync --resolve local     # Use local values for conflicts

Compares local acms.json with the remote schema and merges them. New fields from either side are added. Conflicting values require a resolution strategy.

Options:

Flag	Description
--resolve <strategy>	Conflict resolution: local or remote

acms status

Check the sync status between local and remote schemas.

acms status

Shows which fields exist locally but not remotely, which exist remotely but not locally, and which have conflicting values.

acms generate-types

Generate TypeScript definitions from the current schema.

acms generate-types
acms types              # Alias

Reads acms.json and generates acms.d.ts in the project root. This file provides module augmentation for @useacms/client, giving you full IDE autocomplete and type checking.

acms purge

Remove unused fields based on lastAccessed timestamps in metadata.

acms purge
acms purge --max-age 60       # Fields unused for 60+ days
acms purge --dry-run           # Preview without deleting
acms purge -v                  # Verbose output

Fields that haven’t been accessed within the specified time period are removed from acms.json. The default threshold is 30 days.

Options:

Flag	Description	Default
--max-age <days>	Days since last access before purging	30
--dry-run	Show what would be purged without deleting	false
-v, --verbose	Show detailed output	false

acms --help

Show help for all commands.

acms --help
acms <command> --help    # Help for a specific command

acms -v

Show the CLI version.

acms -v

Global Options

These options are available for all commands:

Flag	Description
--help	Show help information
-v, --version	Show version number

Example Workflow

A typical development workflow looks like:

# Start development
acms dev

# In another terminal, start your app
npm run dev

# Work on your app, fields are auto-registered...

# Generate types manually (if needed)
acms generate-types

# Check what's different from production
acms status

# Pull latest production content
acms pull

# Push local changes to production
acms push

# Clean up unused fields
acms purge --dry-run    # Preview first
acms purge              # Then purge for real

Next Steps

• Learn about the REST API provided by the dev server
• Set up TypeScript support
• Choose a Storage Adapter for production