# Command-line reference
```text
jan [GLOBAL OPTIONS] <subcommand> ... [passthrough args]
```
Without a preferred directory, `jan` and `jan --help` print framework help and how to run `jan use`. With a preferred tree, `--help` lists **live** subcommands plus built-ins.
## Global options
| `-h`, `--help` | — | — | Help for the current prefix (or framework help if none configured) |
| `-V`, `--version` | — | — | Print version |
| `-v`, `--verbose` | — | off | Print preferred-directory resolution on stderr |
| `--cwd DIR` | — | `.` | Working directory for subprocesses and git branch detection |
| `--db FILE` | `JAN_DB` | XDG data local `jan-cli/audit.db` | SQLite audit database |
| `--no-log` | `JAN_NO_LOG` | off | Disable audit logging (`jan test` always implies this) |
| `--branch NAME` | `JAN_BRANCH` | `git rev-parse --abbrev-ref HEAD` | Git branch label stored in the audit log |
Trailing arguments after the matched command path are forwarded only when the leaf defines `exec.passthrough: true`. Use `--` before passthrough args if they start with `-`:
```bash
jan scripts foo run -- --help
```
A single leading `--` after the leaf is stripped (`jan … run create` and `jan … run -- create` are equivalent). Use `run -- --` for a literal first `--`.
## Environment variables
| `JAN_CONFIG_DIR` | Override XDG config dir for `jan use` preference (default `~/.config/jan-cli`) |
| `JAN_DB` | Default audit database path |
| `JAN_BRANCH` | Default `--branch` |
| `JAN_OS` | Override platform filter id for `os:` (`linux`, `macos`, `windows`, …) |
| `JAN_INSTALL_DIR` | Default unpack directory for `jan-install.sh` only |
| `JAN_SCRIPTS_ROOT` | Extra base for resolving relative script `path` entries |
| `JAN_ALLOW_HTTP` | `1` / `true` / `yes` to allow plain HTTP for remote fetches (insecure) |
| `JAN_CACHE_DIR` | Override cache root (default `~/.cache/jan`) |
| `JAN_NO_LOG` | If set, skip audit writes (same as `--no-log`) |
## Spec resolution
`jan` loads YAML from the **preferred directory** saved by `jan use`.
```bash
jan use /path/to/specs # auto-detects scripts.spec.yaml / jan.spec.yaml / jan.yaml
jan use /path/to/specs --root custom.yaml
jan use https://example.com/scripts-jan.zip --sha256 <64-hex>
jan use --show
jan use --clear
```
Entry file preference order: `--root` if given, then `scripts.spec.yaml`, `jan.spec.yaml`, `jan.yaml`.
A common install layout after `jan-install.sh`:
```text
~/.config/jan/scripts/
scripts.spec.yaml
scripts.yaml
git.yaml …
env.sh
```
## Built-in first tokens
These names are reserved and are never taken from YAML:
| [`use`](../cli/use.md) | Set / show / clear preferred directory (works with no tree) |
| [`bundle`](../cli/bundle.md) | Pack the preferred tree into a ZIP |
| [`alias`](../cli/alias.md) | Emit shell aliases for `run` leaves |
| [`config`](../cli/config.md) | Emit / link / unlink / apply / deps host configuration |
| [`list`](../cli/discovery.md) / `search` / `show` / `validate` | Inspect the tree |
| [`audit`](../cli/audit.md) | Query the SQLite log |
| [`cron`](../cli/cron.md) | Run scheduled `run` leaves |
| [`packages`](../cli/packages.md) | Inspect / prune cached package envs |
| [`test`](../cli/test.md) | Run Given/When/Then tests |
## Audit log defaults
| Linux | `~/.local/share/jan-cli/audit.db` |
| macOS | `~/Library/Application Support/jan-cli/audit.db` |
| Windows | `%LOCALAPPDATA%\jan-cli\audit.db` |