Reference: Commands: Each archangel command, its arguments and options, and what it prints. # Commands > Each archangel command, its arguments and options, and what it prints. Run each command with `npx archangel `, or `archangel ` when archangel is on your `PATH`. | Command | What it does | | ----------------------------- | -------------------------------------------------------------------------------------- | | [`check`](#check) | Checks the repository, and shows each problem and a summary. | | [`test`](#test) | Checks the examples of each rule. | | [`rules`](#rules) | Shows each rule as a sentence, what it judged, and what no rule judges. | | [`explain`](#explain) | Shows the place of a file in the architecture, or each rule that judged one import. | | [`why`](#why) | Shows the shortest chain of imports from a file to a file or a package. | | [`watch`](#watch) | Checks, and then checks again after each change. | | [`baseline`](#baseline) | Records the problems of today, or removes the entries that the code does not need now. | | [`lsp`](#lsp) | Starts the language server. | | [`init`](#init) | Writes a starter config. | | [`docs`](#docs) | Shows what a diagnostic code means. | | [`completions`](#completions) | Writes the completion script of a shell. | | [`man`](#man) | Writes the manual page. | ## Options of each command | Option | Values | Default | What it does | | ------------------- | --------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `--config ` | a path | the nearest config | Uses this config. Without it, archangel uses the nearest config in the current folder or above it. | | `--format ` | `text`, `json`, `github`, `sarif` | `text` | The output format. Read [Output and exit codes](/archangel/reference/output-and-exit-codes/). | | `--stats` | | off | Adds the work that archangel did, and the time of each stage. | | `--color ` | `auto`, `always`, `never` | `auto` | When to use color in text output. `auto` uses color on a terminal, unless `NO_COLOR` is set. | | `-h`, `--help` | | | Shows the help. `-h` shows a summary. | | `-V`, `--version` | | | Shows the version. Write it before the command: `archangel --version`. | `rules` and `explain` write only `text` or `json`. For another format, they stop with exit code 2. ## `check` ```sh archangel check [FILES]... ``` Checks the repository with the config, and shows each problem and a summary. This is the command for CI. Terminal ```ansi $ npx archangel check error[may-import]: feature may not import another instance of feature, through "../cart/cart": feature may import only shared, and itself in the same instance --> src/features/checkout/checkout.ts:1:27 | 1 | import { cartTotal } from '../cart/cart'; | ^^^^^^^^^^^^^^ feature may import only shared, and itself in the same instance | = help: remove the import, or move the code to a file whose row permits the import = note: rule: app.feature = note: because: A feature changes alone. Code that two features need goes in shared. checked 5 files and 4 imports: 1 problem For what a code means, run `archangel docs may-import`. ``` With file arguments, archangel shows only the problems of those files. It still checks the whole repository, because a cycle or an empty part depends on all files. The exit code then follows the problems that it shows. The summary counts the files and the imports that archangel checked. It also shows the exceptions and the baseline entries of each rule, and the parts of a preset that find no file. ## `test` ```sh archangel test ``` Checks each accepted and rejected example of each rule, in memory. It prints one line for each example. It fails when an example fails, and when a rule has no rejected example. Terminal ```ansi $ npx archangel test pass no-react-in-shared rejected #1 src/shared/money.ts 1 examples, none failed; 0 rules without a rejected example 2 table rows need no written example; `archangel rules` shows what each covers ``` Read [Examples](/archangel/reference/examples/). ## `rules` ```sh archangel rules [PATH] ``` Shows each rule as a sentence, with its reason, where you wrote it, the files and imports that it judged, and its problems and exceptions. Terminal ```ansi $ npx archangel rules app 2 rows archangel.config.ts:9 because: A feature changes alone. Code that two features need goes in shared. app.feature: feature may import only shared, and itself in the same instance 3 files · 3 imports judged · 1 problem · 0 exceptions app.shared: shared may import only itself 1 file · 0 imports judged · 0 problems · 0 exceptions app.every-file-has-a-kind: a file in no row is not checked here; add `files` to check it 4 files · 0 problems no-react-in-shared archangel.config.ts:16 because: Shared code also runs on the server. files in shared may not import react 1 file · 0 imports judged · 0 problems · 0 exceptions Not judged by any rule: 0 files, 0 imports between repository files. Outside packages that no rule names: none. ``` * A rule that covers no file says that it checks nothing. * A rule from a preset says which preset. A rule that replaces a preset rule says so. * At the end, it lists the files and the imports between repository files that no rule judges, and the outside packages that no rule names. * With a path, it shows only the rules, and the files and imports that no rule judges, under that folder or file. `rules` describes. It does not fail because of a problem in the code. ## `explain` ```sh archangel explain archangel explain : ``` With a file, it shows the part of the file, its groups, the rules that apply to it, its imports and the files that import it. After each rule, it says what the rule judges: the imports of the file (its imports), the imports of the file by other files (imports of it), or both: Terminal ```ansi $ npx archangel explain src/features/checkout/checkout.ts src/features/checkout/checkout.ts part: "feature", instance "checkout" groups: none rules that apply: app.feature app.feature: feature may import only shared, and itself in the same instance (judges its imports) imports: line 1 '../cart/cart' -> src/features/cart/cart.ts ("feature", instance "cart") breaks app.feature imported by: none ``` With a file and a line, it shows each rule that judged the import on that line, with its result, and why each other rule did not judge it: Terminal ```ansi $ npx archangel explain src/features/checkout/checkout.ts:1 src/features/checkout/checkout.ts:1 '../cart/cart' -> src/features/cart/cart.ts file: part feature (instance checkout) target: part feature (instance cart) judged by: app.feature refuses: another instance of feature is not in its row (feature may import only shared, and itself in the same instance) skipped by: app.shared the file is not in shared app.every-file-has-a-kind this rule checks files, not imports no-react-in-shared the file is not in shared ``` * Any line of a statement that spans many lines works. * When a line has more than one import, it shows each of them. * It shows an exception or a baseline entry next to its rule. * A line with no import is an error, with exit code 1. ## `why` ```sh archangel why ``` Shows the shortest chain of imports from a source file to a repository file or a package. Terminal ```ansi $ npx archangel why src/features/checkout/checkout.ts src/shared/money.ts src/features/checkout/checkout.ts:1 imports '../cart/cart' src/features/cart/cart.ts:1 imports '../../shared/money' src/shared/money.ts ``` When no chain exists, it says so and exits with 1. `why` follows each import. It does not know the `stopAt` of a rule, so it can show a chain that a rule stops. ## `watch` ```sh archangel watch ``` Checks, and then checks again after each change. It prints what is new and what is gone after each check. * With `--format json`, it prints one line of JSON for each check. The line has `schemaVersion`, the diagnostics that are `new`, the diagnostics that are `gone`, and a `summary`. The first line lists each diagnostic as new. * When the operating system loses file events, archangel checks again from the start. * When the system has no file watches left, archangel looks for changes at a fixed interval. Each summary then says so, names the limit, and names the command that raises it. In JSON, the field is `polling`. Read [Editors and coding agents](/archangel/guides/editors-and-agents/). ## `baseline` ```sh archangel baseline add archangel baseline prune ``` | Command | What it does | | ---------------- | -------------------------------------------------------------------------------------------------------- | | `baseline add` | Records each current problem in `archangel.baseline.json`, next to the config. | | `baseline prune` | Lowers or removes the entries that the code does not need now. It never adds an entry or raises a count. | Terminal ```ansi $ npx archangel baseline add wrote 3 entries to archangel.baseline.json ``` A check never writes the baseline. Read [Exceptions and baselines](/archangel/guides/exceptions-and-baselines/). ## `lsp` ```sh archangel lsp ``` Starts the language server on standard input and output. Your editor starts it for you. It finds the config as the command line does, from the folder that the editor opened. Read [Editors and coding agents](/archangel/guides/editors-and-agents/). ## `init` ```sh archangel init archangel init --typescript ``` Writes a starter config, with one part for each folder of source files and one rule against import cycles. The config passes from the start. | Option | What it does | | -------------- | ---------------------------------------------------------------------------------------------------- | | `--typescript` | Writes `archangel.config.ts` with `defineConfig`. Without it, `init` writes `archangel.config.json`. | Terminal ```ansi $ npx archangel init --typescript wrote archangel.config.ts with 2 parts: features, shared It imports `@enhance-eng/archangel`, so install the package first: npm install --save-dev @enhance-eng/archangel Write what each part may import in a table, then run `archangel check`; `archangel docs may-import` shows how. ``` When a config already exists, `init` writes nothing and exits with 2. ## `docs` ```sh archangel docs ``` Shows what a diagnostic code means, an example, and what to do. It needs no config. Terminal ````ansi $ npx archangel docs rule-unknown-element # rule-unknown-element A rule or a group names a part, a group or an externals set that the config does not declare. A string without a `/` or a `*` is a name, not a path pattern. The message lists the declared names. ## Example ```ts rule({ files: 'entity', mayNotImport: 'reactt' }) ``` ## What to do Use one of the declared names, or write a package as `{ packages: ['reactt'] }`. With the TypeScript config, the editor shows a misspelt name in a rule as a type error. ```` Each code also has a page on this site. Read [Diagnostic codes](/archangel/reference/diagnostics/). ## `completions` ```sh archangel completions ``` Writes the completion script for `bash`, `zsh`, `fish`, `elvish` or `powershell`. For example, in zsh: ```sh archangel completions zsh > "${fpath[1]}/_archangel" ``` ## `man` ```sh archangel man ``` Writes the manual page of archangel, in roff. The list of commands in `--help` does not show this command. ## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------- | | `0` | The command succeeded, and found no problem. | | `1` | Archangel found a problem, or the answer is no: a failed example, no chain for `why`, no import on the line for `explain`. | | `2` | Archangel could not run: the config, the baseline or the command line has an error. |