# zigman

read the [zig language reference](https://ziglang.org/documentation/master/) in your
terminal — for humans who don't want a browser tab, and for agents that can't render one.
it fetches the reference once, caches it, and prints any section as clean markdown.

source: [tangled.org/zzstoatzz.io/zigman](https://tangled.org/zzstoatzz.io/zigman) · MIT

## install

```
curl -fsSL https://nate.tngl.io/zigman/install.sh | sh
```

macos and linux, aarch64 and x86_64. installs to `$ZIGMAN_INSTALL` or `~/.local/bin`.

## use

type any part of a section's name. a unique match opens it; an ambiguous one lists the
candidates.

```
zigman comptime            # opens the comptime section
zigman error               # several match, so it lists them
zigman -o comptime         # open it in your browser instead
zigman -l                  # the whole table of contents
zigman -V 0.15.1 comptime  # read a specific langref version
```

for everyday workflows, composition, and using zigman from an AI agent, see the
[practical guide](https://nate.tngl.io/zigman/guide.html).

<details>
<summary>build from source</summary>

requires zig 0.16+.

```
git clone https://tangled.org/zzstoatzz.io/zigman
cd zigman
zig build -Doptimize=ReleaseSafe
```

the parser and renderer are a reusable zig module (`src/root.zig`, exported as `zigman`).
`zig build test` runs the unit tests.

</details>

<details>
<summary>shell completion</summary>

add one line to your shell's startup file:

```
# ~/.zshrc   (after compinit)
eval "$(zigman --completions zsh)"

# ~/.bashrc
eval "$(zigman --completions bash)"

# ~/.config/fish/config.fish
zigman --completions fish | source
```

</details>

<details>
<summary>options &amp; paging</summary>

```
-l, --list           list section names instead of rendering
-o, --open           open the section in your browser ($BROWSER, else the OS opener)
-V, --version <ver>  langref version to read (default: master)
-r, --refresh         bypass the cache and refetch
    --no-pager        don't page output on a terminal
-h, --help            show help
```

output is plain markdown. on a terminal it pages through `$PAGER` (default `less -FRX`);
piped, it stays raw — so `zigman comptime | glow -` and `zigman -l | fzf` both work.

</details>