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.

Installation
Quick start
Spec resolution
Command-line reference
Environment variables
Help and discovery
YAML spec format
Script entries: path, dependencies, requires, env
Audit log
Built-in commands
Portable scripts workflow
Examples in this repo
Troubleshooting
License

Installation

From crates.io

cargo install jan-cli

You still need a spec tree on disk (see Quick start).

From source (monorepo)

cd jan-cli
cargo build --release
./target/release/jan use . --root scripts.spec.yaml
./target/release/jan --help

Install a spec bundle (recommended after `cargo install`)

# Export on a machine that has the monorepo (see Portable scripts workflow)
jan use /path/to/jan-cli --root scripts.spec.yaml
jan bundle -o ~/scripts-jan.zip

# Import on any machine
bash /path/to/jan-cli/scripts/jan-install.sh ~/scripts-jan.zip
# → unpacks to ~/.config/jan/scripts/ and runs `jan use` on that dir

jan --help

Or point jan at any existing tree once:

jan use /path/to/jan-cli --root scripts.spec.yaml
jan scripts misc sum help

Quick start

1. Prefer a directory once, then use jan with no path flags:

jan use /path/to/jan-cli --root scripts.spec.yaml
# or: jan use ~/.config/jan/scripts

jan --help                              # lists live subcommands from that tree
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:

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).

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 --show
jan use --clear

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):

~/.config/jan/scripts/
  scripts.spec.yaml
  generated/scripts/   # included fragments (scripts bundle)
  env.sh               # notes that you should `jan use` this directory

Command-line reference

jan [GLOBAL OPTIONS] <subcommand> ... [passthrough args]

Flag	Env	Default	Description
`-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	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

Variable	Purpose
`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_INSTALL_DIR`	Default unpack directory for `jan-install.sh` only
`JAN_SCRIPTS_ROOT`	Base for resolving relative script `path` entries

Help and discovery

jan uses progressive help: place --help or -h immediately after the subcommand prefix you want to inspect.

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:

Field	Type	Description
`about`	string	Shown in help text
`commands`	map	Nested subcommands
`exec`	object	Run a program (`argv`, optional `passthrough`)
`include`	string	Load subtree from another YAML file (relative path)
`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
`requires`	list	External binaries that must exist on `PATH` before run
`env`	map	Environment variables for the child process

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; the first element is the program.

Minimal example

metadata:
  name: myapp
  description: |
    Short description shown at the root help level.

commands:
  hello:
    about: Say hello
    exec:
      argv: ["echo", "hello"]

  run-tool:
    about: Forward args to an external command
    exec:
      argv: ["my-tool", "start"]
      passthrough: true

Nested subcommands

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:

include:
  - fragments/extra.yaml
commands:
  local:
    about: Defined in this file

Per-command include (string) grafts a file as that command's subtree:

commands:
  git:
    include: default/git.yaml

See examples/default.spec.yaml and scripts.spec.yaml for real layouts.

`exec` and passthrough

commands:
  diff:
    about: Git diff with forwarded paths and flags
    exec:
      argv: ["git", "diff"]
      passthrough: true

jan diff -- src/foo.rs
jan diff -w --cached

Without passthrough: true, trailing CLI arguments are rejected.

Platform filtering (`os`)

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.

Script entries: path, dependencies, requires, env

Script-style commands (e.g. the auto-generated scripts tree) use extra fields so inlined runners can call sibling scripts and external tools.

trackusage:
  about: Track command usage
  path: ../scripts/source/trackusage
  dependencies:
    - trackusage-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:
  path: ../scripts/source/issue
  requires: [gh, jq, fzf]
  env:
    ISSUE_EDITOR: vim
  commands:
    run:
      exec:
        argv: ["bash", "-lc", "..."]
        passthrough: true

At run time, jan:

Merges dependencies, requires, env, and path from every node along the matched chain (deeper nodes override env keys).
Resolves transitive dependencies to other scripts' path directories (cycle-checked).
Prepends those directories, then the script's own path, to PATH.
Fails early if any requires binary is missing.

Relative path values are resolved against, in order: --cwd, the spec directory, its parent, then JAN_SCRIPTS_ROOT.

Metadata for the incubator scripts tree is generated from scripts/source/*/script.meta.yaml — see scripts/generate_scripts_jan_spec.py.

Audit log

By default, every leaf execution is logged to SQLite:

Column	Content
`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:

OS	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.

jan use ~/.config/jan/scripts
jan use /path/to/jan-cli --root scripts.spec.yaml
jan use --show
jan use --clear

Afterward, plain jan … and jan --help load that tree.

`jan bundle`

Pack the reachable YAML tree into a ZIP:

jan use . --root scripts.spec.yaml
jan bundle -o ~/scripts-jan.zip
jan bundle --dry-run

Flag	Description
`-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):

jan alias
jan alias --shell zsh -o ~/.config/jan/scripts/aliases.zsh

Flag	Description
`--jan-bin`	Program name on the RHS (default: `jan`)
`--shell`	Header dialect: `sh`, `bash`, or `zsh`
`-o`	Write to a file instead of stdout

Example line:

alias sum='jan scripts misc sum run'

Portable scripts workflow

See docs/PORTABLE_SCRIPTS.md for the full export/import flow.

python3 scripts/generate_scripts_jan_spec.py
cargo build --release
./target/release/jan use . --root scripts.spec.yaml
./target/release/jan bundle -o ~/scripts-jan.zip

# On the target machine:
bash scripts/jan-install.sh ~/scripts-jan.zip
jan --help
jan alias --shell zsh -o ~/.config/jan/scripts/aliases.zsh

Examples in this repo

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

jan use . --root scripts.spec.yaml
jan scripts files basename run -- /tmp/foo/bar.txt

Troubleshooting

`no preferred jan directory configured`

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 relative to the including file's parent directory and must stay under the preferred jan directory for jan bundle.

License

MIT — see LICENSE.md.

jan-cli 0.7.0

jan-cli

Table of contents

Installation

From crates.io

From source (monorepo)

Install a spec bundle (recommended after `cargo install`)

Quick start

Spec resolution

Command-line reference

Environment variables

Help and discovery

Minimal example

Nested subcommands

`include` (split large specs)

`exec` and passthrough

Platform filtering (`os`)

Script entries: path, dependencies, requires, env

Audit log

Built-in commands

`jan use`

`jan bundle`

`jan alias`

Portable scripts workflow

Examples in this repo

Troubleshooting

`no preferred jan directory configured`

`missing required utilities on PATH: fzf`

`unknown script dependency 'foo'`

`unexpected trailing arguments`

`place --help immediately after the subcommand prefix`

Spec include errors

License

jan-cli 0.7.0

jan-cli

Table of contents

Installation

From crates.io

From source (monorepo)

Install a spec bundle (recommended after cargo install)

Quick start

Spec resolution

Command-line reference

Environment variables

Help and discovery

Minimal example

Nested subcommands

include (split large specs)

exec and passthrough

Platform filtering (os)

Script entries: path, dependencies, requires, env

Audit log

Built-in commands

jan use

jan bundle

jan alias

Portable scripts workflow

Examples in this repo

Troubleshooting

no preferred jan directory configured

missing required utilities on PATH: fzf

unknown script dependency 'foo'

unexpected trailing arguments

place --help immediately after the subcommand prefix

Spec include errors

License

Install a spec bundle (recommended after `cargo install`)

`include` (split large specs)

`exec` and passthrough

Platform filtering (`os`)

`jan use`

`jan bundle`

`jan alias`

`no preferred jan directory configured`

`missing required utilities on PATH: fzf`

`unknown script dependency 'foo'`

`unexpected trailing arguments`

`place --help immediately after the subcommand prefix`