zukan 0.2.12

Monster Hunter bestiary in your terminal
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# ZUKAN

<!-- Repository badges -->

[![Rust](https://img.shields.io/badge/rust-2024--edition-orange)](https://www.rust-lang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/lazywalker/zukan/actions/workflows/ci.yml/badge.svg)](https://github.com/lazywalker/zukan/actions)
[![crates.io](https://img.shields.io/crates/v/zukan.svg)](https://crates.io/crates/zukan)
[![docs.rs](https://docs.rs/zukan/badge.svg)](https://docs.rs/zukan)
[![codecov](https://codecov.io/gh/lazywalker/zukan/branch/master/graph/badge.svg)](https://codecov.io/gh/lazywalker/zukan)
[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/lazywalker/zukan/network/updates)
[![Maintenance](https://img.shields.io/maintenance/yes/2026)](https://github.com/lazywalker/zukan)

zukan(図鑑) is a Monster Hunter bestiary in your terminal. 
Renders creature and item icons as half-block ANSI art, 
with an optional info card. All assets are
embedded at compile time — a single offline binary, no external data files.

Asset data comes from the companion repo [zukan-assets](https://github.com/lazywalker/zukan-assets).

## Install

Prebuilt binaries will land on the Releases page once CI is wired. For now,
build from source:

```bash
git clone https://github.com/lazywalker/zukan
cd zukan
make release        # optimized build, ~9 MB binary at target/release/zukan
```

The first build downloads the latest `zukan-assets` Release (~6 MB of icon +
data) into the in-tree `assets/` directory and embeds it.

For asset refresh, local-checkout overrides, make targets, developing notes, see [DEVELOPING.md](DEVELOPING.md).

## Usage

```bash
# Show a monster's icon (sprite → stdout, name → stderr)
zukan rathalos

# Icon + info card
zukan rathalos --detail

# Typo-tolerant: rathalas → rathalos
zukan rathalas

# Multiple monsters, one per block
zukan rathalos rathian diablos

# Items instead of monsters
zukan --item mega-potion --detail

# Browse
zukan --random                  # random monster
zukan --random --game mhwilds   # random monster from Wilds
zukan --list mhwilds            # list all Wilds monsters

# Languages: en (default) / ja / zh
zukan rathalos --detail --lang ja
```

### Flags

| Flag | Purpose |
|---|---|
| `<query>...` | One or more monster/item names (fuzzy, typo-tolerant) |
| `--item` | Query the item database instead of monsters |
| `--detail` | Show the info card next to the icon |
| `--no-card` | Icon only (overrides `--detail` and config) |
| `--width N` | Icon width in terminal columns (0 = default 32 monsters / 24 items; else 24..=48) |
| `--lang en\|ja\|zh` | Display language (`auto` = use config) |
| `--random` | Pick a random monster/item |
| `--game CODE` | Filter `--random` to a game (e.g. `mhw`, `MHW`, `mhwilds`) |
| `--list GAME` | List all monsters in a game, then exit |
| `--hide-name` | Suppress the name line on stderr |
| `--all` / `-a` | Render every match instead of just the best one |

### Output convention

The sprite goes to **stdout**, the name to **stderr** — so you can pipe the art
on its own:

```bash
zukan rathalos --hide-name | some-other-tool
```

## Configuration

Optional config file at `~/.config/zukan/config.toml` (or the platform
equivalent). Explicit CLI flags always win over config.

```toml
language = "en"              # en | ja | zh
default_width = 0            # 0 = built-in defaults (32 monsters / 24 items); else must be 24..=48
default_game = ""            # preferred game code for icon selection
show_card_by_default = false # show the info card without needing --detail
```