CLI

Show general or command-specific help without running a check:

bundle exec archspec help
bundle exec archspec help check
bundle exec archspec check --help

init

bundle exec archspec init
bundle exec archspec init Archspec.rb --force

Creates a starter Archspec.rb.

check

bundle exec archspec check
bundle exec archspec check --config config/architecture.rb
bundle exec archspec check --format json

Runs all rules. The command exits non-zero when violations are found.

Each violation prints as a diagnostic block: the message and rule id, the offending code with the exact span underlined, and the evidence ArchSpec found as a note. On a terminal the output is colored; set NO_COLOR to disable.

[error] models must not depend on controllers [dependencies.forbid]

app/models/user.rb:9:5

     8 │   def controller_peek
  →  9 │     UsersController
       │     ^~~~~~~~~~~~~~~
    10 │   end

  note: User references UsersController

1 architecture violation found.

A clean run prints one line:

ArchSpec passed: 391 files, 407 constants, 11061 facts checked.

Pass paths to report only violations in those files or directories. ArchSpec still analyzes the whole project, so cross-file dependencies resolve, but output is scoped to what you touched:

bundle exec archspec check app/models/user.rb app/services

This is the fast loop after an agent or a person edits a few files. It cannot be combined with --update-todo.

todo

bundle exec archspec check --update-todo

Writes the current violations to the configured todo file. One entry covers every occurrence with the same id (fingerprint), so the count it reports can be lower than the number of violations. Use this for existing apps, not for accepting new regressions. Parse errors are never written to the todo; a file that does not parse has to be fixed.

Each entry records the violation’s stable id and the fields the id is built from: rule, path, message, and evidence. Line numbers are left out on purpose. They are not part of the id, so an edit that only shifts code leaves the file byte-identical, and entries sort by those same fields rather than by location.

bundle exec archspec check --check-todo

Runs the normal check and additionally fails when the todo lists an entry that no current violation matches, because the violation was fixed or is now suppressed locally. These are exactly the entries --update-todo would drop, so a fixed violation cannot linger in the burn-down list. Obsolete entries are printed before the verdict; with --format json they appear under obsolete_todo. With path arguments, only entries under those paths are reported; entries that record no path, such as bare ids, are reported only by an unscoped run. The configured todo file has to exist. Use this in CI instead of regenerating the file and diffing it. It cannot be combined with --update-todo.

bundle exec archspec check --reflect

Before checking, runs the declared producers whose facts are missing or stale, the same way archspec reflect does, then checks against the fresh facts. Producers whose facts are current are not run, so an unchanged project boots nothing. Their progress goes to standard error, so --format json output stays parseable. This boots the application, so keep it to local runs; in CI, commit the facts or run archspec reflect as its own step. Producers declared with auto: true behave this way without the flag. explain accepts --reflect too.

reflect

bundle exec archspec reflect --environment test
bundle exec archspec reflect widgets
bundle exec archspec reflect --config config/architecture.rb

Runs the producers declared with reflect in Archspec.rb (the Rails producer when only facts is declared), each in its own process and all in parallel. Each one boots its framework and writes <facts directory>/<name>.yml. Pass producer names to run only those. --environment sets RAILS_ENV for the producers; otherwise it stays as it is, and the Rails producer defaults to development.

Regenerate after changing the files a producer covers, configuration, or dependencies; check reports stale facts as facts.stale violations, unless it runs with --reflect or the producer is declared with auto: true. A failed producer keeps its previous file and makes the command exit 1. See Rails reflection and Framework integrations.

explain

bundle exec archspec explain app/models/user.rb
bundle exec archspec explain Billing::Invoice

Shows what ArchSpec knows about a file or constant: defined constants, component assignment reasons, suppressions, resolved ancestry, outgoing facts, incoming dependencies, and analysis gaps.

app/models/user.rb

  defined constants: User
  components:
    models: matched file pattern app/models/**/*.rb
  suppressions:
    2-3 │ dependencies.forbid -- migrating legacy coupling
  outgoing facts:
    1:14 │ inherits from ApplicationRecord
     2:3 │ calls has_many
     9:5 │ references UsersController
  incoming dependencies:
    4:7 │ references User
  analysis gaps: 1 unknown receiver

Explaining a constant shows where it is defined, its components, its superclass, and its methods:

User

  kind: class
  file: app/models/user.rb:1
  components:
    models: defined in matched file
  superclass: ApplicationRecord
  resolved ancestors: ApplicationRecord
  unresolved ancestors: ActiveRecord::Base
  instance methods: controller_peek, summary
  class methods: find_active
  outgoing facts:
    1:14 │ inherits from ApplicationRecord
  incoming dependencies: (none)
  analysis gaps: (none)