# Command line

Turn raw data into documented derived tables (useful views). Each recipe in recipes/ turns declared inputs into declared views by running numbered Python steps, and every run is recorded in datapackage.json.

Every command also runs as `python -m useful_views ...`.

``` text
usage: useful-views [-h] [--version] [-C PATH] [--json] command ...
```


# Global options

These go before the command; `-C` and `--json` may also go after it.

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `--version` | show program's version number and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# `useful-views init`

Create the project structure in PATH: raw/, recipes/, work/, useful-views/, a starter README.md, AGENTS.md (for AI coding assistants), .gitignore and datapackage.json. Never overwrites a file.

``` text
usage: useful-views init [-h] [-C PATH] [--json] [--force] [path]
```

| Argument          | Description                                  |
|-------------------|----------------------------------------------|
| `PATH` (optional) | project folder (default: the current folder) |

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |
| `--force` | create the project even in your home folder or at the top of a drive |


# `useful-views example`

Download an example project (raw data and recipes) from the useful-views-data repository, check every file's SHA-256, and set it up like init. Then run: useful-views sync

``` text
usage: useful-views example [-h] [-C PATH] [--json] name [path]
```

| Argument          | Description                          |
|-------------------|--------------------------------------|
| `NAME`            | the example to download, such as pwt |
| `PATH` (optional) | folder to create (default: -example) |

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# `useful-views new-recipe`

Create recipes/NAME/ with a template recipe.toml and a stub step, 01_first_step.py. Both say TODO and are refused until you fill them in.

``` text
usage: useful-views new-recipe [-h] [-C PATH] [--json] name
```

| Argument | Description |
|----|----|
| `NAME` | the recipe's name: lowercase letters, digits and underscores, like pwt_panel |

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# `useful-views run`

Run one recipe. It is checked against the rules first (useful-views rules), then its views are deleted and work/RECIPE/ emptied, each step runs in numeric order as its own process with this Python and the project root as working directory, every declared view must be written, and the run is recorded in datapackage.json and useful-views/README.md. Other recipes are not run.

``` text
usage: useful-views run [-h] [-C PATH] [--json] recipe
```

| Argument | Description                                              |
|----------|----------------------------------------------------------|
| `RECIPE` | the recipe's name, as in pwt_panel or recipes/pwt_panel/ |

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# `useful-views check`

Report what is missing or out of place, every rule a recipe breaks (refused), and recipes that sync would run. Changes nothing. Does not notice changes inside a step's code.

``` text
usage: useful-views check [-h] [-C PATH] [--json]
```

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# `useful-views sync`

Make the views and datapackage.json match the recipe folders, like uv sync. Checks every recipe first and changes nothing if any would be refused. Then removes the records and view files of deleted recipes and outputs, and runs, upstream first, every recipe that is new, changed or missing its views, plus everything downstream of those.

``` text
usage: useful-views sync [-h] [-C PATH] [--json] [--all]
```

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |
| `--all` | run every recipe again, upstream first (sync does not notice edits to a step's code) |


# `useful-views cookbook`

Write cookbook.json at the project root: every recorded recipe, in run order, with its description, inputs, outputs and steps, and the raw inputs the recipes read. Generated from datapackage.json, so the project must be in sync to write it. Commit it, like a lock file.

``` text
usage: useful-views cookbook [-h] [-C PATH] [--json] [--check]
```

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |
| `--check` | do not write; exit 1 if cookbook.json is missing or out of date, or a recipe changed without a sync. Needs no data, so it works in CI |


# `useful-views rules`

List the numbered rules. A refusal names the rule it broke.

``` text
usage: useful-views rules [-h] [-C PATH] [--json]
```

| Option | Description |
|----|----|
| `-h`, `--help` | show this help message and exit |
| `-C` `PATH`, `--project` `PATH` | run as if started in PATH (like git -C), for example a project folder |
| `--json` | print the result as JSON on standard output; other output goes to standard error |


# Exit codes

| Code | Meaning |
|----|----|
| `0` | success |
| `1` | check found problems, or cookbook -check found the cookbook out of date |
| `2` | usage error (unknown command or option, or a bad -C path) |
| `3` | refused or failed (the message says what to fix, and in which file) |
| `130` | interrupted (Ctrl-C) |
| `143` | terminated (SIGTERM, from a CI cancel or a tool's time limit; 129 SIGHUP; 149 Ctrl-Break) |