# jan-cli
`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 delegate to a real program via `exec`. 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.
Full reference documentation is the MkDocs site in this directory: run `./serve.sh` or `m run jan-cli docs-serve`, then open the printed local URL. Build a static tree with `m run jan-cli docs-build` (`jan-cli/site/`).
> [!WARNING]
> A jan tree is executable code, not configuration data. `jan use` makes that
> tree the persistent source of commands for later invocations, and its YAML can
> launch arbitrary programs with your user account's permissions. Only use trees
> you have reviewed and trust. Bundle manifest hashes and remote `sha256` values
> detect corruption or unexpected content changes; they do not authenticate the
> publisher.
---
## Table of contents
- [Documentation site](#documentation-site)
- [Installation](#installation)
- [Security model](#security-model)
- [Quick start](#quick-start)
- [Spec resolution](#spec-resolution)
- [Command-line reference](#command-line-reference)
- [Environment variables](#environment-variables)
- [Help and discovery](#help-and-discovery)
- [YAML spec format](#yaml-spec-format)
- [Script entries: path, dependencies, packages, requires, env](#script-entries-path-dependencies-packages-requires-env)
- [Audit log](#audit-log)
- [Built-in commands](#built-in-commands)
- [Portable scripts workflow](#portable-scripts-workflow)
- [Examples in this repo](#examples-in-this-repo)
- [Troubleshooting](#troubleshooting)
- [License](#license)
---
## Installation
### From crates.io
```bash
cargo install jan-cli
```
You still need a **spec tree** on disk (see [Quick start](#quick-start)).
### From source (monorepo)
```bash
cd jan-cli
cargo build --release
# Prefer a reviewed personal tree (canonical: dotfiles/jan)
./target/release/jan use /path/to/dotfiles/jan
./target/release/jan --help
```
### Install a trusted spec bundle
```bash
# Export a reviewed personal tree (canonical: dotfiles/jan)
jan use /path/to/dotfiles/jan
jan bundle -o ~/scripts-jan.zip
# Import on any machine
bash /path/to/jan-cli/scripts/jan-install.sh ~/scripts-jan.zip
# → verifies archive structure and manifest hashes, then unpacks
# to ~/.config/jan/scripts/; this does not authenticate the publisher
# Review the extracted YAML before making it active.
jan use ~/.config/jan/scripts
jan --help
```
Or point `jan` at any existing tree once:
```bash
jan use /path/to/dotfiles/jan
jan scripts misc sum help
```
---
## Security model
- A preferred tree can execute arbitrary commands and set child environment
variables. `jan` does not sandbox commands or reduce their privileges.
- `jan use` persists an absolute tree path. Future `jan` commands use the current
contents at that path without a signature, content lock, or per-run prompt.
- Local `include:` paths are confined to the preferred tree; included YAML has the
same execution authority as the root file.
- Remote includes and remote `exec.url` scripts are fetched over HTTPS (HTTP only
with `--allow-http` / `JAN_ALLOW_HTTP`) and must declare `sha256`. Cached
objects live under `~/.cache/jan/`. Hashes are integrity checks only.
- `jan bundle` manifests provide integrity checks only. They do not prove who
created a bundle or whether its contents are trustworthy. Bundles cannot contain
remote includes — vendor YAML locally first.
- The SQLite audit database is mutable local telemetry and may contain sensitive
command-line arguments. It is not a tamper-proof security log.
See [SECURITY.md](SECURITY.md) for the detailed threat model and open findings.
---
## Documentation site
```bash
cd jan-cli
./serve.sh # or: m run jan-cli docs-serve
# mkdocs serve → http://127.0.0.1:8000
```
The site covers installation, the YAML spec (including packages, typed inputs, language `exec` forms, cron, and tests), every built-in, maintainer/release workflow, and examples. This README stays a concise front door.
---
## Quick start
**1. Review and trust a tree, prefer it once, then use `jan` with no path flags:**
```bash
jan use /path/to/dotfiles/jan
# or: jan use ~/.config/jan/scripts
jan --help # lists live subcommands from that tree
jan list # script leaves
jan cron --list # cached schedules (requires `jan cron start`)
jan packages # cached uv envs for `packages.uv`
jan scripts misc sum help
jan scripts misc sum run -- 1,2,3
jan use --show # where preference is stored
```
**2. Demo / examples trees in this repo:**
```bash
jan use examples --root demo.spec.yaml
jan --help
jan android skills list
jan use examples --root default.spec.yaml
jan git s
```
---
## Spec resolution
`jan` loads the YAML tree from the **preferred directory** saved by `jan use` (stored in `~/.config/jan-cli/config.json`, overridable with `JAN_CONFIG_DIR`).
```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
```
A remote URL must be an HTTPS jan **bundle zip** (same layout as `jan bundle` /
`jan-install.sh`). The zip SHA256 is required. After verification, the tree is
cached under `~/.cache/jan/trees/<sha256>/` and that path is preferred.
The directory is expected to be a properly formatted jan tree (entry YAML plus any `include:` fragments). After `jan use`, run `jan --help` to list live subcommands.
A common install layout (after `jan-install.sh`):
```text
~/.config/jan/scripts/
scripts.spec.yaml
scripts.yaml # category index (flat layout)
git.yaml …
env.sh # notes that you should `jan use` this directory
```
---
## Command-line reference
```
jan [GLOBAL OPTIONS] <subcommand> ... [passthrough args]
```
| `-h`, `--help` | — | — | List live subcommands from the preferred tree (+ built-ins) |
| `-V`, `--version` | — | — | Print version |
| `-v`, `--verbose` | — | off | Print preferred directory resolution (stderr) |
| `--cwd DIR` | — | `.` | Working directory for subprocesses and git branch detection |
| `--db FILE` | `JAN_DB` | see [Audit log](#audit-log) | SQLite audit database path |
| `--no-log` | — | off | Disable audit logging |
| `--branch NAME` | `JAN_BRANCH` | `git rev-parse` | Git branch label stored in audit log |
**Notes:**
- 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 `-`: `jan scripts foo run -- --help`.
---
## 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:` in YAML (`linux`, `macos`, `windows`, …) |
| `JAN_COMPUTER` | Override registered computer id for `computer:` filtering (see `jan computer set`) |
| `JAN_INSTALL_DIR` | Default unpack directory for `jan-install.sh` only |
| `JAN_SCRIPTS_ROOT` | Base for resolving relative script `path` entries |
| `JAN_ALLOW_HTTP` | Set to `1`/`true` to allow plain HTTP for remote fetches (insecure) |
| `JAN_CACHE_DIR` | Override cache root for remote objects/trees (default `~/.cache/jan`) |
---
## Help and discovery
`jan` uses **progressive help**: place `--help` or `-h` immediately after the subcommand prefix you want to inspect.
```bash
jan --help # live top-level subcommands + built-ins
jan scripts --help # progressive help for a prefix
jan scripts misc sum help # many script leaves also expose a `help` action
```
**Rules:**
- `--help` must come **right after** the prefix being queried. `jan git r --help` is valid; `jan git r rev-parse --help` is not (jan treats trailing `--help` on exec leaves as an error).
- Leaf nodes with `exec` and no children print a short note that they run an external program.
- Subcommands forwarded to external tools (with `passthrough: true`) receive their own `--help` when you pass it after `--` or as trailing args.
---
ptional `metadata` and a `commands` map. Each command node can define:
| `about` | string | Shown in help text |
| `commands` | map | Nested subcommands |
| `exec` | object | Run a program (`argv`, optional `passthrough`) |
| `include` | string or map | Load subtree from YAML, or link a script file as an exec leaf; local `{path, sha256?}` or remote `{url, sha256}` |
| `os` | list | Offer this node only on listed platforms (`linux`, `macos`, `windows`; `darwin` → `macos`) |
| `path` | string | Directory prepended to `PATH` when this script runs |
| `dependencies` | list | Other script **names** whose `path` dirs are prepended first |
| `packages` | map | Package-manager deps (`uv` list / `project` / `requirements`; `pnpm` reserved) |
| `requires` | list | External binaries that must exist on `PATH` before run |
| `env` | map or sections | Public assignments and/or private names (see below) |
| `inputs` | map | Named CLI flags (`--name`) with optional `description`, `required`, `default`; usable as `${{ inputs.name }}` |
| `cron` | string or list | Five-field crontab expression(s); `jan cron` runs the script's `run` leaf when local time matches |
| `tests` | map | Optional Given/When/Then POSIX `sh` tests; `jan test <path>` runs this node and every nested command |
| `exec.url` / `exec.sha256` | strings | Download, verify, and run a remote script (optional `argv` interpreter prefix) |
| `exec.file` / `exec.sha256` | strings | Run a local script under the jan tree (`sha256` optional) |
| `exec.kotlin` | string | Path to `.kt`/`.kts` under the jan tree, or inline Kotlin source; classpath + compile-once |
| `exec.python` | string | Path to `.py` under the jan tree, or inline Python (`python3 -c`); uses `packages.uv` venv when present |
| `exec.node` | string | Path to `.js`/`.mjs`/`.cjs`, or inline JS (`node -e`); uses `packages.pnpm` `NODE_PATH` when present |
| `exec.bash` | string | Path to `.sh`/`.bash`, or inline Bash (`bash -lc`); `argv` is `$1`… |
| `exec.sh` | string | Path to `.sh`, or inline POSIX sh (`sh -c`); `argv` is `$1`… |
| `exec.zsh` | string | Path to `.zsh`/`.sh`, or inline Zsh (`zsh -c`); `argv` is `$1`… |
| `exec.text` | string | Print this literal block (no subprocess). Alias: `exec.cat` |
**Constraints:**
- A node cannot define both `exec` and nested `commands`.
- A node with `include` cannot also define `exec` or `commands` in the same map.
- `exec.argv` must be non-empty unless a language/`url`/`file`/`text` form is set; the first element is the program (for language forms, `argv` is the script's args).
- `exec.url`, `exec.file`, `exec.kotlin`, `exec.python`, `exec.node`, `exec.bash`, `exec.sh`, `exec.zsh`, and `exec.text` are mutually exclusive.
### Minimal example
```yaml
metadata:
name: myapp
description: |
Short description shown at the root help level.
commands:
hello:
about: Say hello
exec:
argv: ["echo", "hello"]
tests:
given_no_args_when_run_then_prints_hello:
then: |
test "$JAN_STATUS" -eq 0
printf '%s\n' "$JAN_STDOUT" | grep -qx hello
run-tool:
about: Forward args to an external command
exec:
argv: ["my-tool", "start"]
passthrough: true
```
### Nested subcommands
```yaml
commands:
android:
about: Android workflows
commands:
skills:
about: Skill tools
commands:
list:
about: List skills
exec:
argv: ["echo", "listing"]
```
Invoke: `jan android skills list`
### `include` (split large specs)
**Root-level** `include` (list) merges top-level command maps from other files:
```yaml
include:
- fragments/extra.yaml
- path: fragments/pinned.yaml # optional local pin
sha256: <64-hex>
- url: https://example.com/shared.yaml
sha256: <64-hex>
commands:
local:
about: Defined in this file
```
**Per-command** `include` grafts a file as that command's subtree (YAML) or as an
exec leaf (any other extension). Local includes do **not** require a hash
(convenient while editing); declare `sha256` only when you want an integrity pin.
Remote includes still require HTTPS + `sha256`.
```yaml
commands:
git:
include: default/git.yaml # YAML subtree (unhashed)
pinned:
include:
path: default/git.yaml
sha256: <64-hex> # optional local pin
shared:
include:
url: https://example.com/git.yaml
sha256: <64-hex>
basename:
about: Print last path component
commands:
run:
include:
path: scripts/files/basename.sh # script → exec leaf
argv: [bash] # optional interpreter prefix
passthrough: true
```
After load, jan retains the include as a link on the node (`jan show` prints
`source:`). `jan validate` re-checks any declared local hashes. `jan bundle`
packs linked script files along with YAML.
Local paths must stay under the preferred tree. See `examples/default.spec.yaml`
and a personal tree such as `dotfiles/jan` for real layouts.
### Local / remote `exec` scripts
```yaml
commands:
local-tool:
about: Run a script from the tree
exec:
file: bin/tool.sh # relative to jan use root
argv: [bash] # optional interpreter prefix
sha256: <64-hex> # optional local pin
passthrough: true
show-docs:
about: Run a verified remote script
exec:
url: https://example.com/show.py
sha256: <64-hex> # required for remote
argv: ["python3"]
passthrough: true
```
Without `argv`, jan runs the file/cache path directly (executable bit set on Unix).
With `argv`, the script path is appended after the prefix (e.g. `bash bin/tool.sh`).
`exec.url`, `exec.file`, `exec.kotlin`, `exec.python`, `exec.node`, `exec.bash`, `exec.sh`, `exec.zsh`, and `exec.text` are mutually exclusive.
### `exec.kotlin`
Point at a `.kt` or `.kts` under the jan use root, **or** inline the program as a
multiline YAML string. jan injects the `packages.gradle` classpath (when
present), compiles `.kt` once into the package cache, and runs with `kotlin` /
`kotlinc -script`. `exec.argv` is forwarded to `main` (or after `--` for
scripts). A single-line value ending in `.kt`/`.kts` is a path; anything else
is inline source (staged as `Inline.kt`).
```yaml
json-summary:
packages:
gradle: [com.fasterxml.jackson.core:jackson-databind:2.18.3]
exec:
kotlin: scripts/files/json-summary.kt
argv: ["${{ inputs.file }}", "${{ inputs.mode }}"]
json-keys:
packages:
gradle: [com.fasterxml.jackson.core:jackson-databind:2.18.3]
exec:
kotlin: |
import com.fasterxml.jackson.databind.ObjectMapper
fun main(args: Array<String>) { /* … */ }
argv: ["${{ inputs.file }}"]
```
For hand-written `java` / `kotlin` / `kotlinc` argv, jan also inserts
`-cp <classpath>` automatically when a gradle env is active and `-cp` is not
already set.
### `exec.python` / `exec.node`
Same path-or-inline pattern for Python and JavaScript. Paths are a single line
ending in `.py` (python) or `.js` / `.mjs` / `.cjs` (node); anything else is inline
source. jan builds `python3 <path| -c code> …argv` or `node <path| -e code> …argv`
and still honors `packages.uv` / `packages.pnpm`. You can keep using plain CLI
eval instead (`argv: ["python3", "-c", "…"]` or `["node", "-e", "…"]`).
```yaml
csv-summary:
packages:
uv:
python: ">=3.11"
packages: [pandas==3.0.5]
exec:
python: |
import sys, pandas as pd
# sys.argv[0] is "-c"; inputs follow
df = pd.read_csv(sys.argv[1])
print(df.shape)
argv: ["${{ inputs.file }}"]
# Equivalent without exec.python:
# exec:
# argv: ["python3", "-c", "import pandas as pd; …", "${{ inputs.file }}"]
birthday:
packages:
pnpm:
node: ">=18"
packages: [chalk@4.1.2]
exec:
node: |
const chalk = require("chalk");
// process.argv[0] is node; inputs start at [1] with -e
console.log(chalk.green(process.argv[1] || "hi"));
argv: ["${{ inputs.name }}"]
```
### `exec.text`
Print a literal block with no subprocess. Use this for `commands.help` (and any
other “just show this text” leaf). `exec.cat` is an alias.
When a command has a `help` child with `exec.text`, jan inlines that body into
`--help` for the command (and for its `run` leaf) and omits `help` from the
subcommand list. Invoking the `help` child still prints the same text and does
not require parent `inputs:`.
```yaml
backup:
about: Backup a path
commands:
help:
exec:
text: |
backup — copy files
Example: jan backup run --path ~/Documents
run:
exec:
bash: |
rsync -a "$1" "$2"
passthrough: true
```
`jan backup --help` prints the `text:` body (plus generated Inputs if declared).
`jan backup help` prints the same body.
### `exec.bash` / `exec.sh` / `exec.zsh`
Same path-or-inline pattern for shells. Inline Bash runs as `bash -lc`, Zsh as
`zsh -c`, and POSIX sh as `sh -c`. jan inserts a `$0` so `$1` / `"$@"` behave
like a normal script. `passthrough: true` appends CLI args after that.
```yaml
run:
exec:
bash: |
echo "$1" | tr ',' '+' | bc
passthrough: true
# Path form:
run-file:
exec:
zsh: scripts/misc/divide.zsh
passthrough: true
```
You can still write `argv: ["bash", "-lc", "…"]` if you prefer.
### `exec` and passthrough
```yaml
commands:
diff:
about: Git diff with forwarded paths and flags
exec:
argv: ["git", "diff"]
passthrough: true
```
```bash
jan diff -- src/foo.rs
jan diff -w --cached
```
Without `passthrough: true`, trailing CLI arguments are rejected.
For inlined POSIX shells (`bash`/`zsh`/`sh` + `-c`/`-lc` + script body), jan inserts a `$0` placeholder before passthrough args so `$1` / `"$@"` behave like a normal script.
A single leading `--` after the leaf is always stripped for passthrough (`jan … run create` and `jan … run -- create` are equivalent; use `run -- --` for a literal first `--`).
### Command tests (`tests` / `jan test`)
Any command node may declare `tests:` — a map whose keys follow
`given_…_when_…_then_…` (spaces or hyphens are fine). Each case is POSIX `sh`
so you assert the **observed** CLI behavior, not the implementation.
`when:` is extra argv for the command the test is declared on — do not repeat the
script path. Omit `when` to invoke that command with no extra args.
```yaml
hello:
exec:
argv: ["echo", "hello"]
tests:
given_no_args_when_run_then_prints_hello:
then: |
test "$JAN_STATUS" -eq 0
printf '%s\n' "$JAN_STDOUT" | grep -qx hello
csv-summary:
tests:
given_a_tiny_csv_when_summarized_then_prints_shape:
given: |
printf 'region,sales\nwest,10\n' > data.csv
when: |
run --file data.csv --head 0
then: |
test "$JAN_STATUS" -eq 0
grep -q 'shape:' "$JAN_STDOUT_FILE"
```
`given` is optional setup. `when` is captured into stdout/stderr/status (a
failing `when` does not abort the test). `then` is required and runs with
`set -e` against:
| `JAN_STATUS` | Exit code of `when` |
| `JAN_STDOUT` / `JAN_STDERR` | Captured streams (trailing newlines preserved) |
| `JAN_STDOUT_FILE` / `JAN_STDERR_FILE` | Same data as files (prefer `grep` on these) |
| `JAN_TEST_TMP` | Isolated cwd for this case |
| `JAN_CMD` | Command path the test is bound to |
| `JAN_BIN` | The `jan` executable under test |
Cases run in a fresh temp directory and never write the audit log (`--no-log` is
implied). Each result line prints the script path and the test name.
```bash
jan test # every test in the tree
jan test scripts files # this command and all nested descendants
jan test scripts files csv-summary
```
### Platform filtering (`os`)
```yaml
commands:
ports:
os: [linux]
about: List listening ports (Linux only)
exec:
argv: ["ss", "-tlnp"]
```
Nodes hidden on other platforms are omitted from help and cannot be invoked.
---
## Time triggers (`jan cron`)
Put a crontab expression (five, six, or seven fields) on a script node or its `run` child.
The **jan cron daemon** ticks every 100 ms and runs matching `run` leaves. Start it with
`jan cron start`; stop with `jan cron stop`.
```yaml
commands:
scripts:
commands:
misc:
commands:
morning-note:
about: Append a daily note
cron: "30 10 * * *" # minute
# cron: "* * * * * *" # every second
# cron: "*/5 * * * * * *" # every 500 ms
commands:
run:
exec:
argv: ["bash", "-lc", "echo hi >> ~/cron.txt"]
```
```bash
jan cron --list # cached schedules (requires daemon)
jan cron --dry-run --at "2026-08-05 10:30"
jan cron --dry-run --at "2026-08-05 10:30:45" # second-level match
jan cron start # start daemon (systemd when available)
jan cron stop
Nicknames: `@yearly` / `@annually`, `@monthly`, `@weekly`, `@daily` / `@midnight`, `@hourly`,
`@every_second`, `@every_100ms`.
After changing `cron:` in YAML, run `jan cron refresh` so the daemon picks up the new schedules.
---
## Script entries: path, dependencies, packages, requires, env
Script-style commands use extra fields so runners can call sibling scripts, pull
package deps, and require host tools.
### `packages` (uv, pnpm)
Declare language package deps separately from `dependencies:` (which names other
jan scripts). Identical declarations share a cached env under
`~/.cache/jan/packages/<manager>/<hash>/` (or `$JAN_CACHE_DIR/…`).
```yaml
# Inline pins
analyze:
about: Analyze a file
packages:
uv: [rich==14.1.0, pathspec==0.12.1]
commands:
run:
exec:
argv: ["python3", "-c", "import rich; …"]
passthrough: true
# Requirements file under the jan use root (every line pinned)
ingest:
packages:
uv:
requirements: deps/ingest.txt
exec:
argv: ["python3", "tools/ingest.py"]
# uv project directory (needs pyproject.toml and uv.lock)
train:
packages:
uv:
project: deps/ml
exec:
argv: ["python3", "-m", "train"]
```
On run, jan requires `uv` on PATH, ensures the hashed env, prepends its `bin/`
to the child PATH, and resolves `python` / `python3` from that venv.
`packages.pnpm` mirrors that for Node:
```yaml
# Inline pins
lint:
packages:
pnpm: [typescript@5.6.3, "@types/node@22.7.4"]
exec:
argv: ["tsc", "--noEmit"]
# pnpm project directory (needs package.json and pnpm-lock.yaml)
build:
packages:
pnpm:
project: deps/web
exec:
argv: ["node", "-e", "console.log(require('lodash').VERSION)"]
```
pnpm envs are installed in the cache, never in your tree: an inline list gets a
generated `package.json`, and `project:` copies `package.json` +
`pnpm-lock.yaml` into the env and runs
`pnpm install --frozen-lockfile --ignore-scripts`. On run, jan prepends
`node_modules/.bin` to PATH (so `tsc`, `zx`, … resolve), sets `NODE_PATH` to the
env's `node_modules` (so `require()` finds packages), and resolves argv[0] from
`.bin` when it matches. Workspace (`workspace:`) and local `file:` links are not
supported, because the manifest is installed outside its original directory.
`packages.gradle` resolves pinned Maven coordinates with the stable Gradle
Java Library plugin (Groovy DSL) into jars under
`~/.cache/jan/packages/gradle/<hash>/lib/`, then injects `CLASSPATH` (and, for
`java` / `kotlin` / `kotlinc` argv or `exec.kotlin`, a `-cp` flag). Each manager
accepts an optional language/runtime minimum that is checked on ensure/run and
included in the env hash:
| `uv` | `python` | `3.11` or `>=3.11` (also passed to `uv venv --python`) |
| `pnpm` | `node` | `18` or `>=18` |
| `gradle` | `java` / `jdk` | `21` or `>=21` |
```yaml
# Preferred: exec.kotlin + packages.gradle
greet:
packages:
gradle:
java: 21
packages: [org.jetbrains.kotlinx:kotlinx-cli-jvm:0.3.6]
exec:
kotlin: packages/kotlin-greet.kts
argv: ["-n", "Ada"]
# Short list form still works (no runtime pin):
greet-simple:
packages:
gradle: [org.jetbrains.kotlinx:kotlinx-cli-jvm:0.3.6]
# Gradle project directory (needs build.gradle(.kts) and gradle.lockfile)
app:
packages:
gradle:
project: deps/jvm
exec:
argv: ["java", "com.example.Main"] # -cp injected automatically
```
Cold builds need `gradle` on PATH (`--no-daemon`); warm hits reuse the jar
cache without spawning Gradle. Project mode attaches an init script that
copies `runtimeClasspath` into the cache — the project must already apply a
JVM plugin that exposes that configuration (e.g. `java`, `java-library`, or
`org.jetbrains.kotlin.jvm`) and must commit a `gradle.lockfile` from dependency
locking.
#### Every dependency must pin an exact version
The env hash is only meaningful if the declaration resolves to one set of
versions, so jan rejects anything looser:
| `uv` inline list | Each entry needs exactly one `==` (or `===`) version — `pandas==2.0.1`. Extras (`pandas[perf]==2.0.1`) and markers (`…; python_version < "3.12"`) are fine |
| `uv` requirements file | Same rule per line; `-r` / `-e` lines are rejected so the file hash covers everything. Comments, `--index-url`, and `--hash=` options are allowed |
| `uv` project directory | Needs a `uv.lock`; jan installs the exported lock (plus the project with `--no-deps`) instead of re-resolving |
| `pnpm` inline list | Each entry needs a full `name@major.minor.patch` — `typescript@5.6.3`, `@types/node@22.7.4`. Prereleases (`zx@8.1.9-beta.1`) are fine |
| `pnpm` project directory | Needs a `pnpm-lock.yaml`; jan installs it with `--frozen-lockfile`, so ranges in `package.json` are fine |
| `gradle` inline list | Each entry needs `group:artifact:version` with an exact version — `com.google.guava:guava:33.3.1-jre`. No `+`, `*`, Ivy ranges, or `latest.release` |
| `gradle` project directory | Needs a `gradle.lockfile`; jan copies `runtimeClasspath` with `--frozen` semantics via the lockfile digest |
Rejected examples: `pandas`, `pandas>=2`, `pandas~=2.0`, `pandas==2.0.*`,
`pandas>=2,<3`, `typescript`, `typescript@latest`, `typescript@^5.6.3`,
`typescript@5.6`, npm aliases or git/file specs, and Maven dynamics like
`g:a:1.+` or `g:a:[1,2)`. A uv direct reference is
accepted only with a hash fragment
(`pkg @ https://…/pkg-1.0-py3-none-any.whl#sha256=<hex>`).
Unpinned inline entries fail when the YAML loads; file, lockfile, and project
rules are enforced on run and reported by `jan validate`.
Inspect the cached envs with [`jan packages`](#jan-packages).
Worked examples in [`examples/packages.spec.yaml`](examples/packages.spec.yaml) —
prefer it, then:
```bash
jan --cwd examples summarize-sales run # uv + pandas CSV rollup
jan --cwd examples pin-report run # pnpm versions via NODE_PATH
jan --cwd examples pin-report cow # binary from node_modules/.bin
jan --cwd examples kotlin-greet run --name Ada # gradle jars + kotlinc -script
```
### `dependencies` / `requires` / `env`
```yaml
path-demo:
about: Demo script that depends on a sibling for PATH
dependencies:
- path-demo-impl
commands:
help:
about: Show description
exec:
argv: ["bash", "-lc", "cat <<'EOF' ..."]
run:
about: Run the script; forwards args
exec:
argv: ["bash", "-lc", "... inlined script ..."]
passthrough: true
issue:
requires: [gh, jq, fzf]
env:
public:
ISSUE_EDITOR: vim
private:
- GH_TOKEN
commands:
run:
exec:
argv: ["bash", "-lc", "..."]
passthrough: true
```
**Environment variables (`env`):**
- **Public** — key/value pairs stored in YAML and assigned on the child.
- **Private** — names only; jan requires them to be set in the host environment, copies their values into the child, and never reads them from the spec.
- Legacy shorthand `env: { FOO: bar }` is treated as public-only.
- When any public or private entry is present, the child does **not** inherit the full parent environment. It receives only: a small essential allowlist (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`, XDG dirs, …), the private copies, and the public assignments. Spec `path`/`dependencies` still control `PATH` as before.
- With an empty `env`, the child inherits the parent environment unchanged (aside from optional `PATH` prepends).
```yaml
# shorthand (public only; restricts child env)
env:
ISSUE_EDITOR: vim
# explicit sections
env:
public:
ISSUE_EDITOR: vim
private:
- GH_TOKEN
```
**Typed inputs (`inputs`):**
Declare named flags on a script (or leaf). jan parses `--name value` / `--name=value` from trailing args, applies defaults, and fails if a `required` input has no value and no default. Optional `type:` and `choices:` are checked **before** values are interpolated into `env.public` or `exec.argv` (so a bad URL never reaches the script). Use `${{ inputs.name }}` in `env.public` values and `exec.argv` strings (not in language bodies).
```yaml
backup:
about: Backup a path
inputs:
path:
description: Source directory
required: true
type: dir
dest:
type: path
default: ~/Backups
url:
description: Absolute HTTPS URL to request
required: true
type: url
proto:
default: tcp
choices: [tcp, udp]
env:
public:
SRC: ${{ inputs.path }}
commands:
run:
exec:
argv:
- bash
- -lc
- rsync -a "$SRC" "${{ inputs.dest }}"
```
`type` values (aliases in parentheses):
| `string` (default) | any non-checked text |
| `url` | absolute `http` or `https` URL with a host |
| `https` (`https-url`) | absolute `https` URL with a host |
| `int` (`integer`) | signed integer |
| `uint` (`unsigned`) | non-negative integer |
| `float` (`number`) | finite number |
| `bool` (`boolean`) | `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off` |
| `path` | well-formed path (need not exist; use for outputs) |
| `file` | existing file, or `-` for stdin |
| `dir` (`directory`) | existing directory |
| `port` | `1`–`65535` |
| `pid` | process id `>= 1` |
| `email` | `local@domain` with a dotted domain |
| `hostname` (`host`) | DNS hostname |
| `ipv4` / `ipv6` / `ip` | IP address |
| `uuid` | hyphenated or 32-hex UUID |
| `hex` | hex digits, optional `0x` |
| `duration` | `30`, `30s`, `5m`, `1h`, `2d` (optional unit) |
| `date` | `YYYY-MM-DD` |
| `json` | parseable JSON |
| `enum` | requires a non-empty `choices:` list |
Empty optional values (including `default: ""`) skip type checks. Unknown `type` names and invalid non-empty defaults are rejected when the spec loads. `choices:` can be combined with any type.
```bash
jan scripts misc backup run --path ~/Documents
jan scripts misc backup run --path ~/Documents --dest /mnt/backup
jan scripts misc backup run --help
```
Unknown long flags are left for `passthrough` when enabled; otherwise they error as unexpected trailing args. Use `--` to stop input parsing and forward the rest.
**At run time**, `jan`:
1. Merges `dependencies`, `requires`, `env`, `inputs`, and `path` from every node along the matched chain (deeper nodes override public `env` keys and input defs; private names are unioned).
2. Resolves typed `--input` flags (and defaults), then interpolates `${{ inputs.* }}` in `env.public` and `exec.argv`.
3. Resolves transitive `dependencies` to other scripts' `path` directories (cycle-checked).
4. Prepends those directories, then the script's own `path`, to `PATH`.
5. Fails early if any `requires` binary is missing, or any `env.private` variable is unset.
6. Resolves `exec.argv[0]` on the `PATH` jan itself inherited, before the prepends above apply, so a spec `path` directory cannot substitute its own `bash` or `python3` for the system one. Directories from `path`/`dependencies` are used only for programs the host does not provide, and an `argv[0]` containing a `/` is used verbatim.
Relative `path` values are resolved against, in order: `--cwd`, the spec directory, its parent, then `JAN_SCRIPTS_ROOT`.
Personal utilities live as inlined YAML under a preferred directory such as `dotfiles/jan`. Edit that tree directly; the old `generate_scripts_jan_spec.py` helper is retired.
---
## Audit log
By default, every **leaf execution** is logged to SQLite:
| `ts` | Unix timestamp |
| `git_branch` | From `--branch`, `JAN_BRANCH`, or `git rev-parse` in `--cwd` |
| `cwd` | Working directory |
| `command_path` | Matched subcommand chain (e.g. `git s`) |
| `argv_json` | Full argv passed to the child process |
| `exit_code` | Child exit code |
| `spec_root_id` | Link to which spec tree was used |
**Default database path:**
| Linux | `~/.local/share/jan-cli/audit.db` |
| macOS | `~/Library/Application Support/jan-cli/audit.db` |
| Windows | `%LOCALAPPDATA%\jan-cli\audit.db` |
Override with `--db` / `JAN_DB`, or disable with `--no-log`.
Useful for agent workflows: each git branch gets a separate audit trail of which `jan` commands ran.
---
## Built-in commands
These are reserved **first-token** subcommands (not defined in your YAML):
### `jan use`
Remember a preferred jan directory under XDG config (`~/.config/jan-cli/config.json`). Works even when no YAML tree is configured yet.
```bash
jan use ~/.config/jan/scripts
jan use /path/to/dotfiles/jan
jan use --show
jan use --clear
```
Afterward, plain `jan …` and `jan --help` load that tree.
### `jan ps`
Show jan processes and how much CPU they are taking collectively (includes
descendants of the cron daemon by default):
```bash
jan ps
jan ps --jan-only
jan ps --avg
```
### `jan bundle`
Pack the reachable YAML tree into a ZIP:
```bash
jan use /path/to/dotfiles/jan
jan bundle -o ~/scripts-jan.zip
jan bundle --dry-run
```
| `-o`, `--output` | Output zip path (default: `jan-spec-bundle.zip`) |
| `--dry-run` | List files instead of writing a zip |
Archive contents:
- All YAML files reachable via `include:` under the preferred directory
- `env.sh` — reminds you to `jan use` the unpack directory
- `manifest.json` — file list and SHA-256 hashes
### `jan alias`
Emit shell aliases for executable leaves (assumes `jan use` is already configured):
```bash
jan alias
jan alias --shell zsh -o ~/.config/jan/scripts/aliases.zsh
```
Alias generation rejects names outside `[A-Za-z_][A-Za-z0-9_-]*` and
shell-quotes every generated command argument.
Declare extra aliases in the spec with `aliases:` on any command node:
```yaml
# Extra names for this jan command (same chain as `run`)
last_branch:
aliases: [lb]
commands:
run:
exec:
bash: |
git branch --sort=committerdate
# Traditional shell aliases (name → RHS)
git:
aliases:
g: git
gs: git status
```
Those aliases also appear on that subcommand's `--help` (for example `jan git --help`).
| `--jan-bin` | Program name on the RHS (default: `jan`) |
| `--shell` | Header dialect: `sh`, `bash`, or `zsh` (default: `zsh`) |
| `-o` | Write to a file instead of stdout |
Example line:
```bash
alias sum='jan scripts misc sum run'
```
### `jan config`
Emit shell fragments, symlink rc files, and run imperative apply steps from
`config:` on command nodes:
```bash
jan config emit --shell zsh -o ~/.config/jan/config.zsh
jan config link
jan config unlink # optional: remove matching managed destinations
jan config apply
jan config deps
```
```yaml
config:
shell: |
setopt AUTO_CD
link:
~/.emacs.d/init.el: |
(message "hi")
apply:
- [git, config, --global, alias.co, checkout]
deps:
ag: the_silver_searcher
fzf: ""
```
See `docs/cli/config.md`. Existing link destinations are skipped with a warning
unless you pass `--force`. Inline `config.link` bodies are written to the
destination; path sources are still symlinked (or `--copy`).
### `jan packages`
Inspect the package environments jan has materialized under
`<cache>/packages/<manager>/<hash>/`, cross-referenced with the preferred tree:
```bash
jan packages # same as `jan packages list`
jan packages list --json
jan packages list --pnpm # or --uv / --gradle, to scope to one manager
jan packages list --orphans # envs no script references anymore
jan packages show csv-summary # by script name, chain, or env hash prefix
jan packages show f16a95ee --json
jan packages path csv-summary --python
jan packages path pin-report --modules
jan packages path kotlin-greet --classpath
jan packages prune # dry-run: orphaned envs unused ≥ 30d
jan packages prune --older-than 7d --min-size 100M --yes
```
`list` prints one row per env (manager, hash, kind, runtime version, size on
disk, last-used age, and the command chains that use it) plus a `declared but not
built yet` section for declarations with no env — including ones whose
`project:` / `requirements:` path fails to resolve.
`show` adds the canonical declaration and the installed packages, read from
`*.dist-info` in the venv, `node_modules` in the pnpm env, or jar names under
`lib/` for gradle, so it works without the manager on PATH.
`path` prints a single path for scripting:
```bash
"$(jan packages path csv-summary --python)" -c 'import pandas; print(pandas.__version__)'
NODE_PATH="$(jan packages path pin-report --modules)" node -e "console.log(require('lodash').VERSION)"
CLASSPATH="$(jan packages path kotlin-greet --classpath)" kotlinc -script -cp "$CLASSPATH" packages/kotlin-greet.kts
```
`prune` removes cached envs that are unused by the preferred tree (orphans),
have not been used for at least `--older-than` (default `30d`), and optionally
exceed `--min-size`. Without `--yes` it only prints candidates. Pass `--all` to
also consider envs still referenced by the tree. Each successful package ensure
updates `.jan-used` so recently run scripts keep their caches.
| `--uv` / `--pnpm` / `--gradle` | Scope to one manager (`list`, `show`, `path`, `prune`) |
| `--json` | Machine-readable output (`list`, `show`, `prune`) |
| `--orphans` | `list` / `prune`: only envs no script in the tree references (prune default) |
| `--all` | `prune`: also consider envs still referenced by the tree |
| `--older-than` | `prune`: minimum age since last use (`30d`, `12h`, `0`, …) |
| `--min-size` | `prune`: only envs at least this large (`100M`, `1G`, …) |
| `--yes` / `-y` | `prune`: actually delete (otherwise dry-run) |
| `--dry-run` / `-n` | `prune`: preview only |
| `--bin` | `path`: print the bin directory (venv `bin`, `node_modules/.bin`, or gradle `lib`) |
| `--python` | `path`: print the venv interpreter (uv only) |
| `--modules` | `path`: print the `node_modules` directory (pnpm only) |
| `--lib` | `path`: print the jar `lib` directory (gradle only) |
| `--classpath` | `path`: print the resolved classpath string (gradle only) |
Envs are keyed by declaration, so scripts with identical `packages:` share a
row, and a `help` leaf under a node that declares packages is listed as a user
too (it inherits the declaration). A script selector that resolves to both a uv
and a pnpm env asks you to narrow with `--uv` / `--pnpm`.
---
## Portable scripts workflow
See [docs/PORTABLE_SCRIPTS.md](docs/PORTABLE_SCRIPTS.md) for the full export/import flow.
```bash
cargo build --release
./target/release/jan use /path/to/dotfiles/jan
./target/release/jan bundle -o ~/scripts-jan.zip
# On the target machine:
bash scripts/jan-install.sh ~/scripts-jan.zip
jan use ~/.config/jan/scripts
jan --help
jan alias --shell zsh -o ~/.config/jan/scripts/aliases.zsh
```
---
## Examples in this repo
```bash
jan use examples --root demo.spec.yaml
jan android skills list
jan use examples --root default.spec.yaml
jan git s
jan git r rev-parse --is-inside-work-tree
# packages.uv + pandas CSV summary
jan use examples --root packages.spec.yaml
jan --cwd examples summarize-sales run
jan --cwd examples summarize-sales run --product gadget
jan use /path/to/dotfiles/jan
jan scripts files basename run -- /tmp/foo/bar.txt
jan list --category files
```
---
## Troubleshooting
### `no preferred jan directory configured`
```bash
jan use /path/to/jan-cli --root scripts.spec.yaml
jan --help
```
### `missing required utilities on PATH: fzf`
Install the named tool or remove it from the node's `requires:` list.
### `unknown script dependency 'foo'`
The `dependencies:` entry must match another command name in the same tree that has a `path:`.
### `unexpected trailing arguments`
The leaf does not set `exec.passthrough: true`. Add it, or drop the extra args.
### `place --help immediately after the subcommand prefix`
Put `--help` right after the prefix you want help for, not after passthrough argv.
### Spec include errors
`include:` paths are resolved from the root directory selected by `jan use`.
Absolute paths, `..` components, and symlinks that escape that root are rejected
both during normal loading and by `jan bundle`.
---
## License
MIT — see `LICENSE.md`.