# CLI

> The shutdown-check CLI reference: the init and test commands, every flag, how the config file is found, the text output and the 0, 1 and 2 exit codes.

Source: https://shutdown.jscrate.dev/docs/cli
Last updated: 2026-09-23

The shutdown-check CLI has two commands. `init` creates a starter config.
`test` starts your service and verifies its behavior after `SIGTERM`.

## Install and open the help

```bash
npm install --save-dev shutdown-check
npx shutdown-check --help
```

The installed help output is:

```text
shutdown-check — verify graceful shutdown with a real in-flight HTTP request

Usage:
  shutdown-check init [--config FILE]
  shutdown-check test [--config FILE] [--json] [--junit FILE]
  shutdown-check --help
  shutdown-check --version

Default config: shutdown-check.json
Exit codes: 0 passed, 1 shutdown check failed, 2 setup/configuration error
```

Running `shutdown-check` without arguments also prints the help.

## Commands

| Command | What it does |
| --- | --- |
| `init` | Write a starter shutdown-check.json |
| `test` | Run the graceful shutdown check |

## Create a config with init

```bash
npx shutdown-check init
```

`init` writes `shutdown-check.json` in the current directory.

| Option | What it does |
| --- | --- |
| `--config FILE` | Read (for `test`) or write (for `init`) this config file instead of `shutdown-check.json`. Paths in it resolve from the file's folder. |

Use `--config` to choose another path:

```bash
npx shutdown-check init --config config/shutdown-check.json
```

The command prints the created path and reminds you to edit the command, port,
and routes. It never overwrites a file. If the target exists, the CLI exits
with code `2`:

```text
shutdown-check: EEXIST: file already exists, open '/home/me/my-service/shutdown-check.json'
```

Edit the existing file, rename it, or choose a different `--config` path. The
[configuration reference](https://shutdown.jscrate.dev/docs/configuration) explains every generated
field.

## Run a check with test

```bash
npx shutdown-check test
```

`test` reads the config, starts the command, waits for readiness, creates
active work, sends `SIGTERM`, and checks the response and process exit.

| Option | What it does |
| --- | --- |
| `--config FILE` | Read (for `test`) or write (for `init`) this config file instead of `shutdown-check.json`. Paths in it resolve from the file's folder. |
| `--json` | Print the full result as JSON on stdout instead of the text timeline. |
| `--junit FILE` | Also write a JUnit XML report with one test case to this file. |

Common forms:

```bash
npx shutdown-check test
npx shutdown-check test --config config/shutdown-check.json
npx shutdown-check test --json
npx shutdown-check test --junit shutdown-result.xml
npx shutdown-check test --json --junit shutdown-result.xml
```

### `--config FILE`

Read a config from another path. Relative paths are resolved from the current
working directory. Inside the file, `cwd` is resolved from the config file's
folder.

### `--json`

Replace the readable text output on stdout with the complete JSON result. This
is useful for scripts and structured CI logs. It does not change the process
exit code.

### `--junit FILE`

Write a JUnit XML report in addition to text or JSON output. The parent folder
must already exist. The file is written before the normal result is printed.

`--json` and `--junit` belong to `test`. Passing either to `init` is an unknown
option.

## Help and version flags

| Flag        | Short | Behavior                                                |
| ----------- | ----- | ------------------------------------------------------- |
| `--help`    | `-h`  | Print help; it must be the first argument               |
| `--version` | `-v`  | Print the installed version; no other argument is valid |

```bash
npx shutdown-check --version
```

## How is the config path resolved?

Without `--config`, the CLI reads `shutdown-check.json` from the directory
where you run the command.

With this layout:

```text
my-service/
├── config/
│   └── shutdown-check.json
└── dist/
    └── server.js
```

run:

```bash
npx shutdown-check test --config config/shutdown-check.json
```

Then use `"cwd": ".."` inside the config if the server command should run from
`my-service/`.

The CLI accepts JSON only. For a TypeScript config, use `defineConfig()` and
`checkShutdown()` from the [Node API](https://shutdown.jscrate.dev/docs/node-api).

## Text output

The default output contains:

1. `PASS` or `FAIL`, followed by a diagnostic code and message;
2. a timeline with milliseconds since the run began;
3. on failure, the last 8 KiB of service stderr and stdout when present.

```text
FAIL SC101: Service exited before becoming ready: code 1

Timeline:
  +    7 ms  process launched — pid=74471
  +   47 ms  process exited — code=1, signal=none
  +  111 ms  check failed — SC101: Service exited before becoming ready: code 1

Service stderr (last 8 KiB):
Error: Cannot find module ./dist/server.js
```

Start with the code, then read the final successful timeline event. The
[diagnostic code pages](https://shutdown.jscrate.dev/docs/codes) give a cause and fix for each failure.

## Errors before the test begins

Command-line and config errors start with `shutdown-check:`. They have no SC
code or timeline because the test did not run.

| Example message                                                                                               | What to change                  |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `Unknown command "run". Run shutdown-check --help.`                                                           | Use `init` or `test`            |
| `Unknown option "--verbose". Run shutdown-check --help.`                                                      | Remove the unsupported flag     |
| `--config requires a file path`                                                                               | Add a path after `--config`     |
| `--junit requires a file path`                                                                                | Add a path after `--junit`      |
| `Cannot read JSON config /path/shutdown-check.json: Error: ENOENT: no such file or directory, open '/path/…'` | Fix the path or create the file |
| `baseUrl must use http://localhost, http://127.0.0.1 or http://[::1]`                                         | Use a supported local origin    |

See [troubleshooting](https://shutdown.jscrate.dev/docs/troubleshooting) for configuration, startup, and
shutdown failures grouped by symptom.

## Exit codes

| Exit code | Meaning |
| --- | --- |
| `0` | passed |
| `1` | shutdown check failed |
| `2` | setup/configuration error |

- `0` means the configured shutdown contract passed.
- `1` means the check ran and returned a failing SC code.
- `2` means invalid arguments, configuration, or setup stopped the check.

A code `1` run can still write JSON and JUnit. A code `2` run has no test
result, so it writes no JUnit report.

## Other package managers

| npm                       | pnpm                            | Yarn                       | Bun                        |
| ------------------------- | ------------------------------- | -------------------------- | -------------------------- |
| `npx shutdown-check test` | `pnpm exec shutdown-check test` | `yarn shutdown-check test` | `bunx shutdown-check test` |

Each command runs the version installed in the current project.

## Related

- [Quick start](https://shutdown.jscrate.dev/docs/quick-start)
- [Configuration reference](https://shutdown.jscrate.dev/docs/configuration)
- [Output and reports](https://shutdown.jscrate.dev/docs/output)
- [Run in CI](https://shutdown.jscrate.dev/docs/ci)
- [Troubleshooting](https://shutdown.jscrate.dev/docs/troubleshooting)