Starter CLI Workflows

Quick start

bun run athas --help

Create a project

bun run athas new my-product

Useful options:

--profile <core|commerce|full>
--profiles <core,commerce,rbac,notifications,wallet,observability>
--entitlements <module.core,module.commerce,...>
--package-manager <pnpm|npm|yarn|bun>
--template <git-url|local-path>
--skip-install
--dry-run
--yes

--profiles is the preferred option for monetization guardrails. The CLI runs hard-remove automation with selected module profiles so non-selected modules are pruned during project bootstrap.

Update from upstream baseline

bun run athas project update --check
bun run athas project update --sync-upstream
bun run athas project update --record-remote-head

This command family reads .athas/project.json, compares template baseline vs remote head, optionally syncs upstream remote, and can record a new local baseline.

Verify module-profile guardrails

bun run athas project verify
bun run athas project verify --profiles core,commerce
bun run athas project verify --profiles core,commerce --entitlements module.core,module.commerce
bun run athas project verify --json
bun run athas project verify --fix-metadata

project verify checks selected profiles against canonical dependency expansion, validates entitlement mapping (module.<profile>), and validates .env.example module flags in backend/admin/client against that resolved profile set (from .athas/project.json by default). Use --profiles (and optional --entitlements) to run verification without metadata. Use --json for CI-friendly machine output. Use --fix-metadata to normalize metadata profiles/entitlements to canonical resolved order before drift evaluation.

Evolve project profiles

bun run athas project evolve --add rbac,notifications
bun run athas project evolve --remove wallet
bun run athas project evolve --add commerce --remove wallet --dry-run
bun run athas project evolve --add rbac --json

project evolve modifies the active module profiles in a running project. It updates .athas/project.json, re-runs module guardrails (hard-remove automation), and updates env flags to match the new resolved profile set.

--add <profiles> adds comma-separated profiles to the current set
--remove <profiles> removes comma-separated profiles (cannot remove core)
--dry-run previews the evolution plan without writing
--json outputs machine-readable evolution plan

After evolving, run athas project verify to confirm guardrail alignment.

Agentation (dev tooling)

The agentation package (^1.3.2) is installed as a root devDependency and lazily loaded in both admin and client consoles via DevAgentation.tsx components. No additional setup is needed. The integration provides development-time AI agent tooling that is tree-shaken from production builds.