# jan
`jan` is a Rust CLI that turns a **YAML command tree** into a discoverable, scriptable interface. Each node can expose nested subcommands (with progressive `--help` at every level) or run a real program. Invocations can be recorded in **SQLite**, keyed by **git branch**, so agents and humans can audit what ran in each checkout.
The binary does **not** ship a built-in command tree. Point it at a directory once with **`jan use <DIR>`**, then `jan --help` lists the live subcommands from that tree.
!!! warning "A jan tree is executable code"
`jan use` makes that tree the persistent source of commands for later invocations. Its YAML can launch arbitrary programs with your user account's permissions. Only use trees you have reviewed and trust. Bundle hashes detect corruption; they do **not** authenticate the publisher.
See [Security model](security.md).
## What jan is for
- Personal script catalogs that stay discoverable (`jan --help`, `jan list`, `jan search`)
- Shared “dotfiles CLI” trees that agents and humans invoke the same way
- Portable bundles (`jan bundle` / `jan-install.sh`) moved between machines
- Python, Node, and JVM deps that materialize into hash-keyed caches instead of polluting the tree
## Feature map
| YAML trees | Nested `commands` with `about`, `os`, `include`, `exec` |
| Exec leaves | `argv`, language sources (`python` / `node` / `kotlin` / shells), remote `url`, local `file`, literal `text` |
| Packages | Pinned `uv`, `pnpm`, and `gradle` environments under `~/.cache/jan/packages/` |
| Inputs | Named `--flags` with types, choices, defaults, and `${{ inputs.name }}` |
| Env | Public assignments, private host copies, `pass` store lookup |
| Cron | Sub-minute schedules; `jan cron start` / `jan cron stop` for the daemon |
| Process view | `jan ps` — jan processes and collective CPU usage |
| Tests | Given/When/Then POSIX `sh` cases via `jan test` |
| Config | `config:` emit / link / unlink / apply / deps via `jan config` |
| Audit | SQLite log of leaf executions, keyed by git branch |
| Portable | ZIP bundles with `manifest.json` integrity checks |
Current crate version: **0.15.0** (`jan-cli` on crates.io). The installed binary is named **`jan`**.
## Where to go next
1. [Install](installation.md) the binary
2. [Quick start](quickstart.md) with the examples tree
3. Author a [YAML spec](spec/overview.md)
4. Browse [built-in commands](cli/use.md)
```bash
jan use /path/to/reviewed-tree
jan --help
```