Skip to content
Crucible

Commands

Core Commands

Section titled “Core Commands”

forge init

Section titled “forge init”

Interactive wizard that detects AI tools, configures sources, and writes .crucible/forge.config.yaml.

Terminal window
forge init          # interactive setup
forge init --force  # re-initialize existing config

forge sync

Section titled “forge sync”

Fetches from all configured sources, resolves targets, and places files for each assistant.

Terminal window
forge sync            # sync all sources
forge sync --dry-run  # preview changes without writing
forge sync --silent   # suppress output (for scheduled runs)

Features:

  • Multi-source parallel fetching via Promise.allSettled
  • SHA-256 change detection — only writes when content changed
  • Per-file error recovery — failed files don’t abort the sync
  • Rollback on mutation failure

forge status

Section titled “forge status”

Shows drift between last sync state and current filesystem.

Terminal window
forge status

Drift statuses: | Status | Meaning | |—|—| | in-sync | File matches last sync | | modified | Locally changed since last sync | | deleted | Removed from disk, still in sync state | | remote-updated | Changed in source since last sync | | conflict | Both local and remote changed | | new-in-source | Exists in source, not yet synced | | removed-from-source | Was synced, no longer in source |

forge health

Section titled “forge health”

SLI dashboard showing operational metrics.

Terminal window
forge health

Displays: last sync time, sync frequency, drift count, source reachability, active assistants, log and report statistics.

Configuration Commands

Section titled “Configuration Commands”

forge config

Section titled “forge config”

Interactive config editor with section-based menu.

Terminal window
forge config       # interactive menu
forge config show  # display current config

Sections: assistants, sources, sync settings, scheduler, telemetry.

Source Management Commands

Section titled “Source Management Commands”

forge source list

Section titled “forge source list”
Terminal window
forge source list

Shows configured sources with type, detail, synced file counts, and advanced options.

forge source add

Section titled “forge source add”
Terminal window
forge source add

Add a new source interactively. Supports git (SSH/HTTPS) and local paths.

forge source remove

Section titled “forge source remove”
Terminal window
forge source remove

Remove a source with optional cleanup of synced files and sync state.

forge source edit

Section titled “forge source edit”
Terminal window
forge source edit

Edit existing source configuration with pre-filled current values.

Scheduler Commands

Section titled “Scheduler Commands”

forge scheduler install

Section titled “forge scheduler install”
Terminal window
forge scheduler install

Registers an OS-level auto-sync task:

  • macOS — launchd
  • Linux — crontab
  • Windows — Task Scheduler

forge scheduler uninstall

Section titled “forge scheduler uninstall”
Terminal window
forge scheduler uninstall

Removes the scheduled sync task.

forge scheduler status

Section titled “forge scheduler status”
Terminal window
forge scheduler status

Shows next run time, schedule description, and scheduler status.

Other Commands

Section titled “Other Commands”

forge telemetry

Section titled “forge telemetry”
Terminal window
forge telemetry        # show status and what's collected
forge telemetry reset  # clear stored events

Opt-in anonymous usage tracking. Local JSONL storage. No data sent anywhere by default.

forge uninstall

Section titled “forge uninstall”
Terminal window
forge uninstall

Removes .crucible directory, uninstalls scheduler, deletes all synced files. Requires confirmation.

Global Options

Section titled “Global Options”
Flag Description
--global Operate on global config (~/.crucible/forge.config.yaml)
--log-level <level> Set log level: silent, error, warn, info, debug, trace
--version Show version
--help Show help