Purpose: Document all Reactium CLI commands with workflow-oriented guidance on WHEN and WHY to use each command, command combinations, and decision trees for common development tasks.
Target Audience: Claude Code assisting developers to recommend proper CLI usage, workflow patterns, and command combinations for efficient Reactium/Actinium development.
The Reactium CLI (npx reactium) provides 30+ commands for project initialization, code generation, plugin development, backend operations, and package management. Commands are organized by context (Reactium frontend vs Actinium backend) and purpose.
Key Concepts:
- Reactium commands: Frontend development (components, routes, styles, hooks)
- Actinium commands: Backend development (cloud functions, collections, middleware)
- Core commands: Project management (init, auth, update, install)
- Workflow combinations: Common multi-command patterns for complete features
Purpose: Initialize a new Reactium (frontend) or Actinium (backend) project
Source: CLI/commands/init/index.js:1-103, CLI/commands/init/actions.js:1-113
When to use:
- Starting a new Reactium web application
- Starting a new Actinium API server
- Evaluating the framework (quick start)
How it works:
- Prompts for project type:
app(Reactium) orapi(Actinium) - Downloads GitHub repo archive (master.zip or tagged release)
- Extracts to current directory with strip=1 (removes top-level folder)
- Optionally runs
npm installfor dependencies
Flags:
-t, --type [flavor]- Project type:app(Reactium) orapi(Actinium)
Example workflows:
# Initialize Reactium application (prompts for type)
npx reactium init
# Initialize Reactium application with flag
npx reactium init -t app
# Initialize Actinium API server
npx reactium init -t apiIntegration: Downloads from GitHub repos configured in config.reactium.repo and config.actinium.repo
Common gotchas:
- Must be run in empty directory or will overwrite files
- Uses
decompresswith strip:1, so repo structure flattens - Always runs
npm installafter extraction (no skip option)
Purpose: Authenticate against Actinium registry or custom Actinium server for publishing plugins/packages
Source: CLI/commands/auth/index.js:1-148
When to use:
- Before publishing plugins to Reactium registry
- Setting up authentication for custom Actinium server
- Validating existing session
- Clearing stale authentication
How it works:
- Prompts for username/password (or accepts via flags)
- Authenticates against Actinium Parse Server
- Stores session token in CLI config for subsequent commands
- Supports custom server/app configuration
Flags:
-u, --username [username]- Username-p, --password [password]- Password-a, --app [app]- Actinium app ID-s, --server [server]- Actinium server URL-V, --validate [validate]- Validate existing session-r, --restore [restore]- Restore default app/server values-c, --clear [clear]- Clear existing session
Example workflows:
# Authenticate with prompts
npx reactium auth
# Authenticate with credentials
npx reactium auth -u Bob -p 'MyP455VV0RD!'
# Authenticate against custom server
npx reactium auth -s 'https://my-actinium/api' -a 'MyActinium'
# Validate existing session
npx reactium auth -v
# Clear session (logout)
npx reactium auth -c
# Restore default registry settings
npx reactium auth -rIntegration: Saves credentials to .arcli/config.json for use by package publish and other registry commands
Common gotchas:
- Custom server/app values persist in config.json
- Use
-rto restore defaults before publishing to public registry - Session validation doesn't prompt for credentials if invalid
These commands generate Reactium frontend code (components, routes, styles, hooks, domains).
Purpose: Generate React component with optional route, hooks, domain, and stylesheet
Source: Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/component/index.js:1-213, reactium-arcli.js:1-158
When to use:
- Creating new page components
- Creating reusable UI components
- Building feature components with full architecture (hooks + domain + route)
How it works:
- Prompts for destination, component name, route path
- Prompts for optional: Reactium hooks file, domain file, stylesheet
- Generates component file + optional supporting files
- Hook-driven extensibility via
arcli-component-*hooks
Flags:
-d, --destination [path]- Component directory location-n, --name [name]- Component name (PascalCase)-r, --route [route]- Route path (e.g.,/about,['/page-1', '/page-2'])-H, --hooks [hooks]- Generatereactium-hooks-*.jsfile for plugin registration-D, --domain [domain]- Generatereactium-domain-*.jsfile for DDD domain-s, --style [type]- Generate style partial file with prefix:default,mixins,variables,base,atoms,molecules,organisms,overrides-u, --unattended [unattended]- Skip confirmation prompts
Generated files:
ComponentName.jsx- Functional component with useSyncStatereactium-hooks-componentname.js- Component registration hook (if--hooksflag used)reactium-route-componentname.js- Route definition array (if--routespecified)reactium-domain-componentname.js- DDD domain declaration (if--domainflag used)[prefix]-ComponentName.scss- Style partial file (if--styleflag used, e.g.,_reactium-style-ComponentName.scss)
Example workflows:
# Create full page component with all features
npx reactium component \
-d src/app/components/AboutPage \
-n AboutPage \
-r '/about' \
-H \
-D \
-s atoms
# Create simple reusable component (no route)
npx reactium component \
-d src/app/components/Button \
-n Button
# Create component at labeled path
npx reactium label -p src/app/pages -k labels.pages
npx reactium component -d '[labels.pages]/Home' -n HomePageHook integration: Fires arcli-component-input, arcli-component-confirm, arcli-component-conform, arcli-component-preflight, arcli-component-actions hooks for customization
Common gotchas:
- Route format must be string
'/path'or array['/path-1', '/path-2'] - Component name auto-converted to PascalCase
-s, --styleflag accepts prefix types (default,variables, etc.), NOT file extensions (scss,less,css)- Style files are always
.scssextension, regardless of type (type controls prefix/compilation order) -H, --hooksflag generates hooks file that registers component in Component registry onplugin-init-D, --domainflag generates domain file for DDD organization- Generated route uses dynamic import for code splitting
Purpose: Generate standalone route file without component (for existing components)
Source: Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/route/index.js:1-156, reactium-arcli.js:1-93
When to use:
- Adding routes to existing components
- Creating multiple routes for same component
- Organizing routes separately from components
How it works:
- Prompts for destination and route path
- Generates route definition file
- Uses same generator as component command
Flags:
-d, --destination [path]- Route file directory-r, --route [route]- Route path
Example workflows:
# Add route to existing component directory
npx reactium route \
-d src/app/components/AboutPage \
-r '/about'
# Create multi-route file
npx reactium route \
-d src/app/components/HomePage \
-r '["/", "/home"]'Integration: Route files auto-discovered by routing system via routes-init hook
Purpose: Generate DDD style partial file with configurable prefix for compilation order control
Source: Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/style/index.js:1-153, reactium-arcli.js:1-91, styleTypes.cjs:1-34
When to use:
- Adding style partials to existing components
- Creating variables, mixins, or override files with correct compilation order
- Organizing component styles by atomic design levels (atoms, molecules, organisms)
How it works:
- Prompts for destination (fuzzypath selector, default:
src/app/components) - Prompts for style type (8 prefix options that control compilation order)
- Sets
params.style = trueand callscomponentGen(same generator as component command) - Generates
.scssfile with selected prefix + component name from directory basename - Auto-discovered by DDD style partial system via
_reactium-style-*pattern
Flags:
-d, --destination [path]- Component directory location-t, --type [type]- Style prefix type (controls compilation order):default→_reactium-style-ComponentName.scssmixins→_reactium-style-mixins-ComponentName.scssvariables→_reactium-style-variables-ComponentName.scssbase→_reactium-style-base-ComponentName.scssatoms→_reactium-style-atoms-ComponentName.scssmolecules→_reactium-style-molecules-ComponentName.scssorganisms→_reactium-style-organisms-ComponentName.scssoverrides→_reactium-style-overrides-ComponentName.scss
-u, --unattended [unattended]- Skip confirmation prompts
Generated files:
[prefix]-ComponentName.scss- Style partial file (always.scssextension)- Examples:
- Type
variables→_reactium-style-variables-Button.scss - Type
default→_reactium-style-Button.scss - Type
overrides→_reactium-style-overrides-Modal.scss
- Type
Example workflows:
# Create default style partial (prompts for type)
npx reactium style -d src/app/components/Button
# Create variables partial (compiles early in order)
npx reactium style \
-d src/app/components/Button \
-t variables
# Create overrides partial (compiles late in order)
npx reactium style \
-d src/app/components/Modal \
-t overrides
# Create atomic design level partial
npx reactium style \
-d src/app/components/ui/InputField \
-t atoms
# Unattended mode (skip prompts)
npx reactium style \
-d src/app/components/Modal \
-t default \
-uIntegration: Auto-discovered by ddd-styles-partial hook via _reactium-style-* filename pattern. Prefix determines compilation order in final CSS bundle.
Compilation Order (from styleTypes.cjs):
variables- Compiled first (for SCSS variables)mixins- Compiled second (for SCSS mixins)base- Base stylesatoms- Atomic design atomsmolecules- Atomic design moleculesorganisms- Atomic design organismsdefault- Default component stylesoverrides- Compiled last (for overriding other styles)
Common gotchas:
- Type is NOT file extension - All files are
.scss, type controls prefix/order - Invalid types:
scss,less,cssare NOT valid type values - Valid types:
default,mixins,variables,base,atoms,molecules,organisms,overrides - Stylesheet name always derived from directory basename (e.g.,
Buttondirectory →*-Button.scss) - Files with
_reactium-style-*prefix are auto-discovered - manual import NOT required
Purpose: Generate Reactium plugin hook file
Source: Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/hook/index.js:1-151, reactium-arcli.js
When to use:
- Adding plugin lifecycle hooks
- Integrating with Reactium systems (routing, components, etc.)
- Creating extensible plugin patterns
Generated: reactium-hooks-*.js file with Hook.register pattern
Example workflows:
# Add hook file to component directory
npx reactium hook -d src/app/components/MyComponentPurpose: Generate DDD domain file
Source: Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/domain/index.js:1-149, reactium-arcli.js:1-78
When to use:
- Organizing code by domain-driven design principles
- Grouping related DDD artifacts in specific domains
How it works:
- Prompts for destination directory
- Derives domain name from directory basename
- Uses same
componentGenas component command withparams.domain = true
Flags:
-d, --destination [path]- Directory to save the domain file-u, --unattended [unattended]- Skip confirmation prompts
Generated: reactium-domain-*.js file with domain name declaration
Example workflows:
# Create domain file (name derived from directory basename)
npx reactium domain -d src/app/components/UserProfile
# Unattended mode
npx reactium domain -d src/app/components/Checkout -uNote: Domain name is automatically derived from the basename of the destination path (e.g., UserProfile directory → domain name UserProfile)
Purpose: Label a directory path for reuse in other commands
Source: CLI/commands/label/index.js:1-248
When to use:
- Creating shortcuts to frequently used directories
- Standardizing component locations across team
- Simplifying command flags with labeled paths
How it works:
- Prompts for path and label key
- Saves to CLI config.json as object path
- Other commands resolve
[label]syntax to actual path
Flags:
-p, --path [path]- Path to label (supports[root],[cwd]aliases)-k, --key [key]- Config key (e.g.,labels.components)
Example workflows:
# Label components directory
npx reactium label \
-p '[cwd]/src/app/components' \
-k 'labels.components'
# Use label in component command
npx reactium component \
-d '[labels.components]/Button' \
-n Button
# Label pages directory
npx reactium label -p src/app/pages -k labels.pagesIntegration: Path aliases resolved by CLI commands during parameter processing
Common gotchas:
- Labels stored in
.cli/config.json(not version controlled by default) - Use object-path format for keys (e.g.,
labels.my-path) [root]= CLI install directory,[cwd]= current working directory
Purpose: Install Reactium or Actinium plugin packages from registry or NPM
Source: CLI/commands/package/install/index.js:1-90
When to use:
- Installing plugins from Reactium registry
- Installing plugins from NPM
- Reinstalling plugins listed in
package.jsonreactiumDependencies/actiniumDependencies
Flags:
--app [app]- Actinium app ID--npm- Install from NPM instead of registry--server [server]- Actinium server URL
Example workflows:
# Install plugin from registry
npx reactium package install @atomic-reactor/admin
# Install from NPM
npx reactium package install @atomic-reactor/admin --npm
# Reinstall all registered plugins (devops)
npx reactium package installNote: For installing NPM dependencies, use npm install directly. This command is specifically for Reactium/Actinium plugin packages.
Purpose: Update Reactium CLI and framework dependencies
Source: CLI/commands/update/index.js
When to use:
- Updating to latest Reactium CLI version
- Updating framework after new releases
- Checking for available updates
Example workflows:
# Update CLI and framework
npx reactium updatePurpose: Generate new CLI command with template structure
Source: CLI/commands/cli/command/index.js:1-255 (template-based generator)
When to use:
- Creating project-specific CLI commands
- Building reusable command packages
- Extending CLI with custom workflows
Generated files:
index.js- Command registration (NAME, COMMAND, ID exports)actions.js- Action sequence stepsgenerator.js- Generator wrapper
Template: Uses handlebars templates from CLI/commands/cli/command/template/
Flags:
-c, --command [command]- Command name-d, --destination [destination]- Path where the command is saved (supportscwd/,app/,root/shortcuts)-o, --overwrite [overwrite]- Overwrite existing command (default: false)
Example workflows:
# Generate custom command (with prompts)
npx reactium commander
# Generate custom command with flags
npx reactium commander -c deploy -d cwd/deploy
# Creates structure:
# .cli/commands/deploy/
# ├── index.js (command registration)
# ├── actions.js (action sequence)
# └── generator.js (generator wrapper)Goal: Add a complete page with route, component, styles
Commands:
# Single command approach (recommended)
npx reactium component \
-d src/app/components/AboutPage \
-n AboutPage \
-r '/about' \
-H \
-D \
-s atomsGenerates:
AboutPage.jsx- React componentreactium-hooks-aboutpage.js- Component registrationreactium-route-aboutpage.js- Route definitionreactium-domain-aboutpage.js- Domain declaration_reactium-style-AboutPage.scss- Style partial file (default type)
Result: Fully functional page accessible at /about
Goal: Route to component that already exists
Commands:
# Generate route file only
npx reactium route \
-d src/app/components/ExistingComponent \
-r '/new-path'Manual step: Update route file to import existing component
Goal: Build shared component library with consistent structure
Commands:
# Label components directory
npx reactium label \
-p src/app/components/common \
-k labels.common
# Generate components with label
npx reactium component -d '[labels.common]/Button' -n Button
npx reactium component -d '[labels.common]/Input' -n Input
npx reactium component -d '[labels.common]/Modal' -n ModalGoal: Develop, test, and publish a Reactium plugin
Commands:
# 1. Create plugin as workspace module
mkdir -p reactium_modules/@myorg/my-plugin
cd reactium_modules/@myorg/my-plugin
npm init -y
# 2. Generate CLI commands (optional)
npx reactium commander -c my-command -d cwd/my-command
# 3. Develop plugin with local testing
# (code your plugin with reactium-hooks.js, etc.)
# 4. Test plugin in local project
# (Reactium auto-discovers workspace modules)
# 5. Publish to NPM
npm publish
# 6. Publish to Reactium registry (optional)
npx reactium auth
npx reactium package publishGoal: Same component accessible via multiple routes
Commands:
# Create component with array route
npx reactium component \
-d src/app/components/Profile \
-n Profile \
-r '["/profile", "/user", "/account"]' \
-HGenerated route:
export default [
{ id: 'route-Profile-1', exact: true, component, path: ["/profile", "/user", "/account"] }
];→ npx reactium component -r '/path' -H -s atoms
→ npx reactium component -n MyComponent
→ npx reactium route -r '/path'
→ npx reactium style -d src/app/components/MyComponent -t default
→ npx reactium commander -c my-command
→ npx reactium init -t app
→ npx reactium init -t api
→ npx reactium package install [name]
→ npx reactium update
→ npx reactium auth
→ npx reactium label -p [path] -k [key]
Commands fire hooks for extensibility:
Component command hooks:
arcli-component-input- Customize promptsarcli-component-confirm- Custom confirmationarcli-component-conform- Transform parametersarcli-component-preflight- Pre-generation checksarcli-component-actions- Modify action sequencearcli-file-gen- Transform generated file content
Route command hooks:
arcli-route-inputarcli-route-confirmarcli-route-conformarcli-route-preflightarcli-route-actions
Global hooks (arcli-hooks.js files):
- Loaded from all
**/arcli-hooks.jsfiles during bootstrap - Can register hooks for any command
- Useful for organization-wide CLI customizations
Commands use handlebars templates from template/ directories:
Component templates:
index-functional.hbs- Functional componentroute.hbs- Route definitiondomain.hbs- Domain declarationreactium-hooks.hbs- Component registrationreactium-style.hbs- Stylesheet
CLI command templates:
index.js.hbs- Command structureactions.js.hbs- Action sequencegenerator.js.hbs- Generator wrapper
Generated files auto-discovered by framework:
reactium-hooks-*.js→ Loaded on plugin initreactium-route-*.js→ Discovered by routing systemreactium-domain-*.js→ Domain artifact placement_reactium-style-*.scss→ Style partial compilation
Instead of repeating long paths, label them:
npx reactium label -p src/app/components -k labels.components
npx reactium component -d '[labels.components]/Button' -n ButtonUse all flags for full-featured pages:
npx reactium component \
-d src/app/pages/About \
-n AboutPage \
-r '/about' \
-H \
-D \
-s atomsKeep routes separate from components for flexibility:
# Component without route
npx reactium component -n Profile
# Add routes later
npx reactium route -d src/app/components/Profile -r '["/profile", "/user"]'Skip prompts in automation:
npx reactium component \
-d src/app/components/Button \
-n Button \
-uAlways auth before registry operations:
npx reactium auth
npx reactium package publish- Input:
my-component→ Output:MyComponent(PascalCase) - className: Auto-generated as lowercase
my-component
- String:
'/path'for single route - Array:
['/path-1', '/path-2']for multiple routes - Invalid:
'/path-1', '/path-2'(not an array)
npx reactium init extracts to current directory and will overwrite existing files. Always run in empty directory.
The -t, --type flag on npx reactium style controls the prefix, not the file extension:
- Type
default→_reactium-style-MyComponent.scss(default compilation order) - Type
variables→_reactium-style-variables-MyComponent.scss(compiled first) - Type
overrides→_reactium-style-overrides-MyComponent.scss(compiled last) - All files are
.scssextension regardless of type - Invalid:
-t scss(not a valid type) - Valid:
-t default,-t variables,-t atoms, etc.
Generated reactium-hooks-*.js (via -H flag) registers component in Component registry. Without this, hookableComponent won't find it.
npx reactium auth saves session to .arcli/config.json. Use --clear or --restore to reset.
Labels saved to .cli/config.json in current working directory. Not global unless saved to ~/.arcli/config.json.
Problem: Command not found: my-command
Solutions:
- Check command discovery locations in
.cli/config.json - Verify
index.jsexportsNAME,COMMAND,ID - Run
npx reactium --helpto see discovered commands - Check globby depth limit (default: 25)
Problem: Template variables not substituted
Solutions:
- Verify handlebars syntax:
{{variable}}not{variable} - Check params object contains expected keys
- Ensure template file has
.hbsextension - Check template directory location matches componentGen path
Problem: Files generated in unexpected directory
Solutions:
- Check
destinationparameter afterformatDestination()transform - Verify path aliases resolved correctly (
[root],[cwd],[labels.x]) - Use absolute paths for debugging
Problem: Generated route doesn't appear in app
Solutions:
- Verify file named
reactium-route-*.js - Check file exports default array of route objects
- Restart dev server (routes discovered on init)
- Check
routes-inithook not filtering route
init- Initialize Reactium/Actinium projectauth- Authenticate for registryinstall- Install dependenciesupdate- Update CLI and framework
component- Generate component + optional route/hooks/domain/styleroute- Generate standalone route filestyle- Generate stylesheet partialhook- Generate Reactium hook filedomain- Generate domain file
label- Label directory pathsconfig- Manage CLI configuration
commander- Generate custom CLI command
package publish- Publish to registrypackage install- Install plugin from registry or NPM
- Bootstrap:
CLI/bootstrap.js:1-247 - Command Discovery:
CLI/arcli-node.js:111-194 - Init Command:
CLI/commands/init/index.js:1-104,actions.js:1-114 - Auth Command:
CLI/commands/auth/index.js:1-149 - Label Command:
CLI/commands/label/index.js:1-249 - Component Command:
Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/component/reactium-arcli.js:1-159 - Route Command:
Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/route/reactium-arcli.js:1-94 - Component Generator:
Reactium-Core-Plugins/reactium_modules/@atomic-reactor/reactium-core/.cli/commands/reactium/component/componentGen.cjs:1-86 - Generator Wrapper:
CLI/lib/generator.js:1-20 - CLI Command System:
CLAUDE/CLI_COMMAND_SYSTEM.md
- CLI Command Discovery and Extensibility - Deep dive on command discovery architecture
- CLI Template System - Template generation patterns
- Hook System - Hook integration for CLI extensibility
- DDD Discovery - Auto-discovery of generated artifacts
- Style Partial System - Stylesheet compilation