AI Role Factory CLI

Build and maintain a personalised executive workspace from the command line. The CLI uses the same generation engine as the hosted AI Role Factory.

This package is in public preview and requires Node.js 24.

Create a workspace

Start the interactive builder:

npx @ai-role-factory/cli@preview

Or generate from a saved JSON or YAML config:

npx @ai-role-factory/cli@preview \
  --config ./my-company.yaml \
  --output ./workspaces/my-company

The result is a local folder you can open in Claude Code, Cursor, Codex, or another coding assistant.

Check a downloaded workspace

Every new workspace contains .ai-role-factory/instance.json. The manifest records its factory release and a checksum and ownership rule for each generated path.

Run the read-only workspace doctor:

npx @ai-role-factory/cli@preview doctor ./workspaces/my-company

Doctor checks required files, unresolved setup values, instruction drift, invalid JSON or YAML, integration consistency, and unsafe secret placement. It does not change the workspace.

Preview an update

Generate a fresh target with the same role, modules, and intake settings. Then compare it with the installed workspace:

npx @ai-role-factory/cli@preview plan-update \
  ./workspaces/my-company \
  --target ./workspaces/my-company-new

For machine-readable output:

npx @ai-role-factory/cli@preview plan-update \
  ./workspaces/my-company \
  --target ./workspaces/my-company-new \
  --json

The plan reports files that could be added, updated, preserved, removed, or blocked by a conflict. It does not apply changes.

Ownership and privacy

• Factory-owned files can change only while the installed copy still matches its generated baseline.
• Customer-owned files, including profiles, operating scope, session notes, MCP config, environment files, and secrets, are always preserved.
• Mixed files stop for review when both the customer and factory changed them.
• New customer files are preserved.
• The maintenance commands run locally and send no workspace telemetry.

There is no write-capable updater in the current release.

Help

Read the public workspace maintenance guide for file ownership examples, update-plan meanings, backups, and common questions.

If you prefer not to use a terminal, use the hosted builder. It needs no local setup.