jan-cli 0.7.0

YAML-defined CLI trees with progressive help, optional exec aliases, merged extra specs, and SQLite audit logging keyed by git branch
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

# Portable scripts via jan-cli

Move the incubator `scripts` collection between machines using a YAML spec bundle and the `jan` binary.

## Prerequisites (target machine)

- **`jan`** built or installed (`cargo install --path jan-cli` or copy a release binary).
- **`bash`** (all inlined runners use `bash -lc`).
- Interpreters and tools each script needs (`python3`, `git`, `docker`, `zsh`, `ffmpeg`, etc.) — the bundle does not install these.
- After install: **`jan use <install-dir>`** (done automatically by `jan-install.sh` when `jan` is on `PATH`).

## Layout after import

Recommended install directory:

```text
~/.config/jan/scripts/
  scripts.spec.yaml
  generated/scripts/
    scripts.yaml
    git.yaml
    …
  env.sh              # written by `jan bundle`
  aliases.zsh         # optional: from `jan alias -o aliases.zsh`
```

## Export (source machine)

From the monorepo, regenerate when `scripts/source` changes:

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

The zip contains all reachable YAML under the preferred directory plus `manifest.json` and `env.sh`.

## Import (target machine)

```bash
bash jan-cli/scripts/jan-install.sh ~/scripts-jan.zip
# or:
#   mkdir -p ~/.config/jan/scripts
#   unzip -o ~/scripts-jan.zip -d ~/.config/jan/scripts
#   jan use ~/.config/jan/scripts

jan --help
jan scripts misc sum help
jan scripts misc sum run -- 1,2,3
```

Generate shell aliases (requires `jan use` already):

```bash
jan alias --shell zsh -o ~/.config/jan/scripts/aliases.zsh
source ~/.config/jan/scripts/aliases.zsh
sum 1,2,3
```

## Environment variables

| Variable | Purpose |
|----------|---------|
| `JAN_CONFIG_DIR` | Where `jan use` stores preference (default `~/.config/jan-cli`) |
| `JAN_INSTALL_DIR` | Default unpack directory for `jan-install.sh` (default `~/.config/jan/scripts`) |

## Regeneration

Do **not** hand-edit `jan-cli/generated/scripts/*.yaml`. Regenerate from source:

```bash
python3 jan-cli/scripts/generate_scripts_jan_spec.py
```

## Trust boundary

Bundles contain executable script source inlined in YAML. Only import bundles you trust. `manifest.json` lists file paths and SHA-256 hashes for verification.

## Known limitations

- Cross-script PATH dependencies are resolved only when listed in `script.meta.yaml` `dependencies`.
- Scripts that `source` files outside their directory (e.g. `$LIB_MACHINE_TYPES`) may still fail until metadata or layout is fixed.
- Zsh completions from the legacy `scripts/install.sh` flow are not included.