astro-hd is a fast command-line tool that calculates a Human Design chart from a birth date, time and UTC offset. Planetary positions come from the astro-rust library; the report is rendered as a colorized terminal table, JSON or YAML. The ask command answers questions about the chart using a local RAG knowledge base.
cargo install astro-hdThe binary is installed as astro-hd (usually into ~/.cargo/bin). The default build includes RAG support. For a lean binary without it use:
cargo install astro-hd --no-default-featuresastro-hd --date 1986-05-19 --time 12:00 --utc +6--date is YYYY-MM-DD, --time is HH:MM, --utc is the UTC offset of the birthplace (e.g. +3, -5, +5.5).
| Flag | Short | Description |
|---|---|---|
--date |
-d |
Birth date in YYYY-MM-DD format. |
--time |
-t |
Birth time in HH:MM format. |
--utc |
-u |
Timezone offset (e.g., +3, -5, +5.5). |
--scenarios |
Comma-separated display scenarios (see below). | |
--topic |
Thematic output set: full, core, career, psyche, genekeys, venus, variables, or a user-defined topic. Conflicts with --scenarios. |
|
--detail |
Detail level: detailed (default) or compact. |
|
--format |
-f |
Output format: table (default), json, yaml. |
--lang |
-l |
Language: en (default), ru, es. |
--save |
Save output to a file. Without a value, the name is generated as hd_chart_<date>_<time>.txt. |
|
--no-pager |
Disable interactive paging of long table output. |
Birth-related flags (-d, -t, -u, --lang, --scenarios, --topic, --detail) are global and also work with the ask subcommand.
| Command | Description |
|---|---|
ask |
Ask a question using the knowledge base and the calculated chart. |
kb |
Manage the RAG document registry (kb add/list/remove/reindex/search/verify/path). |
models |
Install, inspect, stop or remove the models used by ask (models install/status/stop/remove). |
config |
Show or change default output settings. |
topics |
List built-in and user-defined output topics (topics list). |
ask options:
| Flag | Description |
|---|---|
QUESTION |
Natural-language question; defaults to the scenario question. |
--query-scenario |
Query scenario: reading, career, psyche, genekeys, or a custom one. |
--index |
Build or refresh the embedding index, then exit. |
--force |
Ignore the embedding cache when used with --index. |
--top-k |
Number of retrieved fragments (overrides rag.top_k). |
--answer-format |
text (default) or json. |
Long table output is shown page by page when the terminal is interactive:
Space — next page, Enter — next line, q — quit. Paging is skipped
automatically when output is redirected or piped, and can be disabled with
--no-pager.
The report is assembled from independent blocks (scenarios), always rendered in this canonical order:
| Scenario | Content |
|---|---|
core |
Date, Type, Profile, Authority, Strategy |
incarnation |
Incarnation Cross with its four gates; --detail detailed adds the cross and gate descriptions |
centers |
Centers with normal/distorted behavior |
channels |
Active channels |
planets |
Combined Design/Personality planet table; --detail detailed adds gate/line descriptions |
circuits |
Circuit scores |
variables |
Motivation, Vision, Environment, Diet |
relationships |
Fears, sexuality and love by gate |
business |
Business keys for active gates |
genekeys |
Gene Keys of active gates: shadow, gift and siddhi, ordered by planet significance |
venus |
Venus Sequence: six spheres and steps 11–23 |
--detail compact drops the optional descriptions (core, incarnation, channels, planets, genekeys, venus, centers, circuits).
Built-in topics:
| Topic | Description | Scenarios | Detail |
|---|---|---|---|
full |
All blocks with descriptions (default output) | all scenarios | detailed |
core |
Identity and bodygraph mechanics | core, centers, channels, planets, circuits | detailed |
career |
Core plus business gates (work, money) | core, centers, channels, planets, circuits, business | detailed |
psyche |
Core plus relationships (fear, sexuality, love) and centers | core, centers, relationships | detailed |
genekeys |
Core plus planets, Gene Keys, channels and circuits | core, channels, planets, genekeys, circuits | detailed |
venus |
The Gene Keys set plus the Venus Sequence | core, channels, planets, genekeys, venus, circuits | detailed |
variables |
Core plus variables (motivation, vision, environment, diet) | core, variables | detailed |
JSON and YAML output always contain the full chart; scenarios affect only the table.
astro-hd ask answers questions using a local knowledge base (books, notes, methodology docs) plus the chart calculated by the CLI. Retrieval runs on in-process fastembed embeddings, generation runs on llama.cpp: the CLI downloads a prebuilt llama-server and a background runtime keeps it warm across calls — the first ask starts the server, every later CLI call extends its lease, and once no call arrives within rag.keep_alive_secs (30 minutes by default) the runtime stops the server and exits. Nothing has to be compiled or installed — everything works offline after the first download.
cargo build --release # RAG is included by default
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 \
--query-scenario career \
"How do my channels show up in work and money?"The first call downloads the embedding model, the Qwen3-4B GGUF checkpoint and the llama.cpp build (all SHA-256 verified), so later runs are offline. All of it is managed by the binary:
astro-hd models install # download everything `ask` needs
astro-hd models status # what is installed, how much space it takes, where
astro-hd models stop # stop the background runtime and its llama.cpp server
astro-hd models remove # delete the models and llama.cpp buildsastro-hd ask --index, kb reindex and kb search only provision the embedding model, because indexing and retrieval do not call the chat model. Set "auto_pull_models": false in the RAG config to disable automatic downloads; in that case ask fails with a hint to run models install.
For a lean binary without RAG:
cargo build --release --no-default-featuresDocuments are not copied: kb add registers each file by its absolute path, and the indexer reads it in place. Chunks are embedded once and cached in the platform data directory, so subsequent runs only embed new or changed files.
Query scenarios compose a question with a chart topic:
| Scenario | Chart blocks |
|---|---|
reading |
core, channels, planets, centers, relationships (compact) |
career |
core, business, channels, planets, centers, circuits |
psyche |
core, centers, relationships |
genekeys |
core, channels, planets, genekeys, circuits |
astro-hd ask --index # (re)index and exit
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --query-scenario genekeys
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --answer-format json "What does the chart say about relationships?"
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --topic career "..." # override the chart topicRAG settings live in config.json:
{
"rag": {
"local_embed_model": "multilingual-e5-small",
"device": "auto",
"top_k": 6,
"chunk_chars": 1200,
"chunk_overlap": 150,
"max_chart_chars": 16000,
"num_ctx": 16384,
"auto_pull_models": true,
"keep_alive_secs": 1800,
"query_scenarios": {
"my_reading": {
"default_question": "What should I focus on this year?",
"scenarios": ["core", "centers", "variables"]
}
}
}
}rag.cache_dir overrides the data folder that holds the registry, the index and converted documents.
Loading the model takes seconds, so astro-hd keeps llama-server warm across calls instead of starting and stopping it every time. The first call that needs inference starts a small detached process — the same binary running the hidden __runtime command — which owns the server and a lease:
- every CLI call (not just
ask) extends the runtime lease byrag.keep_alive_secs; - when no call arrives within that window, the runtime stops the server and exits, removing its state files;
- plain chart calculations never start the runtime — they only keep a running one alive;
ask --index,kb reindexandkb searchnever start it, because indexing and retrieval use fastembed only.
astro-hd models status # runtime state, llama.cpp port and backend
astro-hd models stop # stop the runtime and its server immediatelyWith a runtime up, models status adds a block like:
Runtime: running (pid 12345, up 42s, idle timeout 1800s, expires in 1758s)
llama.cpp: not started
| Key | Default | Description |
|---|---|---|
keep_alive_secs |
1800 |
How long the runtime (and its llama.cpp server) stays alive after the last CLI call. 0 disables the runtime and starts a one-shot server per ask. |
The server is restarted automatically when a setting that affects it changes (device, num_ctx, or the model file), and a crashed or upgraded runtime is replaced on the next call. If the runtime cannot be started, ask falls back to a one-shot server for that request.
Nothing RAG-related is compiled or downloaded at build time: ask installs what it needs on the first run, and the same artifacts can be managed explicitly.
astro-hd models install # embedding model + GGUF checkpoint + llama.cpp build
astro-hd models status # what is installed, where, and the runtime state
astro-hd models stop # stop the background runtime and its server
astro-hd models remove # delete the models and llama.cpp buildsComponent Details State Size Path
Embeddings multilingual-e5-small installed 464.8 MB <data>/rag/fastembed
Chat model qwen3-4b-q4-k-m installed 2.3 GB <data>/rag/models/qwen3-4b-q4-k-m
llama.cpp cuda installed 721.8 MB <data>/rag/llama
Runtime: running (pid 12345, up 42s, idle timeout 1800s, expires in 1758s)
llama.cpp: port 51234 (cuda)
models remove stops the running runtime first, then deletes the three folders above and prints the freed space. The vector index is kept — it stays valid when the same embedding model is installed again; use kb reindex to rebuild it from scratch.
| Artifact | Size | Purpose |
|---|---|---|
multilingual-e5-small (fastembed/ONNX) |
~470 MB | embeddings |
Qwen3-4B-Q4_K_M.gguf + tokenizer/config |
~2.3 GB | answers |
llama-server (llama.cpp) |
15–520 MB | inference, depends on the detected GPU |
| Key | Default | Description |
|---|---|---|
device |
auto |
auto picks a GPU when one is detected, gpu requires one, cpu forces CPU. |
local_embed_model |
multilingual-e5-small |
Also all-minilm-l6-v2, all-minilm-l6-v2-q, bge-small-en-v1.5. |
num_ctx |
16384 |
Context window passed to llama.cpp as --ctx-size. |
Pick the device without editing the config:
astro-hd config --set-device auto # GPU when detected (default)
astro-hd config --set-device gpu # fail instead of falling back to CPU
astro-hd config --set-device cpu # always CPUThe CLI detects the GPU and downloads the matching prebuilt llama.cpp build:
| Platform | GPU build | Download |
|---|---|---|
| Windows x86_64 | CUDA when nvidia-smi is present, else Vulkan |
520 MB / 30 MB |
| Linux x86_64 / arm64 | Vulkan (llama.cpp ships no CUDA build for Linux) | 30 MB |
| macOS arm64 / x64 | Metal | 11 MB |
| no GPU / other targets | CPU | 11–17 MB |
With device = "auto", a GPU build that fails to start (missing driver, out of memory) falls back to the CPU build instead of aborting the request. The llama.cpp build is started with all layers offloaded to the GPU (-ngl 99); when both an integrated and a discrete GPU are visible, the discrete one is selected (llama-server --list-devices prints the ids). Model files live in <data>/rag/models/, the binaries in <data>/rag/llama/, the embedding cache in <data>/rag/fastembed/; kb path prints the folder.
Documents stay where they are. kb add records the absolute path of each document in registry.json, and the indexer reads it from that path:
astro-hd kb path # print the data folder (registry, index, converted)
astro-hd kb add ./books/venus.md # register and index a file in place
astro-hd kb add ./books # register and index every supported file in a folder
astro-hd kb list # id, state, size, date and path of each document
astro-hd kb remove venus.md # remove by id, path or unique suffix
astro-hd kb verify # check that files exist and are unchanged
astro-hd kb reindex # rebuild the embedding index
astro-hd kb reindex --force # ignore the cache and re-embed everything
astro-hd kb search "profile 1/3" # retrieval preview without generationRegistry and index live in the platform data directory (Windows: %APPDATA%\nimblemo\astro-hd\data\rag, Linux: ~/.local/share/astro-hd/rag, macOS: ~/Library/Application Support/com.nimblemo.astro-hd/rag); rag.cache_dir overrides it.
kb list states:
| State | Meaning |
|---|---|
ok |
The file exists and matches the registration. |
stale |
The file changed on disk; the next index run re-embeds it. |
missing |
The file is gone; it is skipped by the indexer until you kb remove it. |
kb add registers the documents and immediately embeds the new or changed chunks (using the configured fastembed model). Long runs report progress: the conversion size and duration, the chunk count per document, and the embedding percentage. kb remove drops the document's cached chunks, so the change takes effect without a full reindex. The next ask picks the registry up automatically; kb reindex rebuilds everything explicitly. kb verify exits with a non-zero status when any document needs attention.
kb add also accepts documents the index cannot read directly — .pdf, .docx, .doc, .docm, .odt, .rtf, .epub, .html, .htm, .xhtml. They are converted to Markdown with Firecrawl /v2/parse; only the generated .md is registered, and it is stored in the data folder under converted/ (the source file is never modified):
astro-hd config --set-ocr-key fc-... # stored in config.json
astro-hd kb add ./books/venus.pdf # → <data>/rag/converted/<id>-venus.md
astro-hd kb add ./books --force # re-convert every supported file in the folderThe key can also come from the FIRECRAWL_API_KEY environment variable (rag.ocr.api_key_env); a key stored in the config takes precedence. astro-hd config shows whether a key is set (only the last four characters are printed).
kb list shows such documents with a from <original> line. Removing them deletes the generated Markdown as well.
Conversion is layout-aware with OCR fallback for scanned pages, files up to 50 MB per request. Settings live in rag.ocr:
| Key | Default | Description |
|---|---|---|
enabled |
true |
Convert non-text documents in kb add; false rejects them. |
api_url |
https://api.firecrawl.dev/v2/parse |
Parse endpoint (self-hosted instances allowed). |
api_key_env |
FIRECRAWL_API_KEY |
Environment variable holding the API key. |
api_key |
— | Key stored directly in the config; set it with astro-hd config --set-ocr-key <KEY> (takes precedence over the env var). |
mode |
auto |
PDF strategy: auto (text first, OCR fallback), fast (text only), ocr (force OCR). |
max_pages |
— | Parse only the first N pages, to cap cost. |
timeout_secs |
600 |
HTTP timeout for one conversion. |
Without the rag feature (cargo build --no-default-features) conversion is unavailable and only text files are accepted.
Defaults are stored in config.json:
| OS | Path |
|---|---|
| Windows | %APPDATA%\nimblemo\astro-hd\config\config.json |
| Linux | ~/.config/astro-hd/config.json |
| macOS | ~/Library/Application Support/com.nimblemo.astro-hd/config.json |
{
"language": "en",
"output": {
"detail": "detailed",
"scenarios": ["core", "channels", "planets", "centers"]
},
"topics": {
"my_reading": {
"detail": "compact",
"scenarios": ["core", "centers"]
}
}
}An empty scenarios list means all scenarios. User-defined topics take precedence over built-in ones.
astro-hd topics list # list topics with descriptions
astro-hd config # show current defaults
astro-hd config --list-scenarios # list scenarios and topics
astro-hd config --set-lang ru # change default language
astro-hd config --set-scenarios core,centers # set default scenarios
astro-hd config --set-detail compact # set default detail level
astro-hd config --set-topic career # apply a topic as default
astro-hd config --set-device auto # inference device (auto | gpu | cpu)
astro-hd config --set-ocr-key fc-... # store the Firecrawl key for PDF → MarkdownPriority: CLI flags (--scenarios / --topic / --detail) > config file > built-in defaults.
Concise table output:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic coreExport to JSON:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --format json > chart.jsonSave to a file:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --save my_chart.txtAnother language (English is the default):
astro-hd -d 1986-05-19 -t 12:00 -u +6 --lang ruSelected scenarios:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --scenarios core,channels,centers --detail compactTopic:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic careerVenus Sequence:
astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic venusNo Rust toolchain required — every release ships ready-to-run binaries for:
| Platform | Target triple |
|---|---|
| Linux x86_64 (glibc) | x86_64-unknown-linux-gnu |
| macOS Intel | x86_64-apple-darwin |
| macOS Apple Silicon | aarch64-apple-darwin |
| Windows x86_64 | x86_64-pc-windows-msvc |
Static musl builds are not published: the embedding model runs on ONNX Runtime, which ships no musl binaries. Use cargo build --no-default-features to get a chart-only static binary from source.
Files are named astro-hd-v<VERSION>-<TARGET> (astro-hd-v<VERSION>-<TARGET>.exe on Windows), and each binary has a .sha256 checksum next to it. Browse them on the releases page.
Release binaries include RAG support. Chart calculation works fully offline; ask downloads the models and the matching llama.cpp build (GPU when one is detected) on first use.
VERSION=0.5.0
TARGET=x86_64-unknown-linux-gnu # see the table above for other platforms
BIN="astro-hd-v${VERSION}-${TARGET}"
BASE="https://github.com/nimblemo/astro-hd/releases/download/v${VERSION}"
curl -fLO "${BASE}/${BIN}"
curl -fLO "${BASE}/${BIN}.sha256"
sha256sum -c "${BIN}.sha256" # macOS: shasum -a 256 -c "${BIN}.sha256"
chmod +x "${BIN}"
sudo install -m 755 "${BIN}" /usr/local/bin/astro-hd$Version = "0.5.0"
$Bin = "astro-hd-v$Version-x86_64-pc-windows-msvc.exe"
$Base = "https://github.com/nimblemo/astro-hd/releases/download/v$Version"
Invoke-WebRequest "$Base/$Bin" -OutFile $Bin
Invoke-WebRequest "$Base/$Bin.sha256" -OutFile "$Bin.sha256"
$expected = (Get-Content "$Bin.sha256").Split(' ')[0].Trim().ToUpper()
$actual = (Get-FileHash $Bin -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "Checksum mismatch" }
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\astro-hd" | Out-Null
Move-Item $Bin "$env:LOCALAPPDATA\astro-hd\astro-hd.exe" -Force
$env:Path += ";$env:LOCALAPPDATA\astro-hd" # add permanently via System Properties → Environment Variablescargo install --git https://github.com/nimblemo/astro-hd --tag v0.5.0git clone https://github.com/nimblemo/astro-hd.git
cd astro-hd
cargo build --release
# binary: ./target/release/astro-hd- Rust — only for
cargo install/ building from source. - Nerd Font (optional) — the table uses Nerd Font symbols for zodiac signs and planets. Install e.g. JetBrainsMono Nerd Font and select it in your terminal for the best look.
- RAG models (optional) — required only for
astro-hd ask. The embedding model, the Qwen3-4B GGUF checkpoint and the llama.cpp binary (~2.8 GB in total) are downloaded into the data folder on the first run. - Chart calculation is fully offline: gate and center descriptions are embedded in the binary, so no data files or network access are needed.
src/main.rs: entry point and command dispatch.src/cli.rs: CLI argument parsing and terminal output formatting.src/calc.rs: core Human Design logic and chart assembly.src/astro_calc.rs: astronomical calculations wrapper.src/scenario.rs: display scenarios, detail levels and topics.src/query.rs: RAG query scenarios composed with chart topics.src/rag.rs: Rig-based retrieval, embedding cache and answer generation (included by default).src/library.rs: document registry (registry.json),kb add/list/remove/verify.src/ocr.rs: PDF/DOCX/EPUB → Markdown conversion via Firecrawl.src/llama.rs: llama.cpp supervision — binary download, server startup and shutdown.src/runtime.rs: background runtime that keeps llama.cpp warm between CLI calls (lease,models status/stop).src/local.rs: model cache — GGUF checkpoint downloads and fastembed embeddings.src/venus.rs: Venus Sequence map (steps 11–23) assembled from existing positions.src/config.rs: user configuration and config path resolution.src/data/: data models and the embedded gates database.data/: gate database and Venus Sequence JSON files bundled into the binary at build time.locales/: translations (en,ru,es).
cargo build # debug build
cargo test --all-targets
cargo fmt --all --check
cargo clippy --all-targets -- -D warningsbuild.rs downloads the gate database into data/ if the files are missing (they are committed to the repository, so a normal build needs no data downloads; Cargo dependencies are fetched as usual).
target/ grows quickly because every feature set (default, --no-default-features) and the debug profile keep their own artifacts. Dependencies are compiled without debug info ([profile.dev.package."*"] in Cargo.toml), and the rest can be pruned safely:
cargo clean --profile dev # drop debug artifacts, keep the release build
cargo clean # drop everything (~10 GB)
cargo sweep -t 7 # optional: remove artifacts unused for 7 days (cargo install cargo-sweep)Set CARGO_INCREMENTAL=0 for one-off builds to skip the incremental cache (~5 GB), and avoid running manual builds while rust-analyzer is checking the workspace — they contend for the same lock and can leave half-written artifacts.
cargo bench # criterion micro-benchmarks
cargo run --example load_test --release # throughput, 10 000+ chartsTypical performance results:
- Calculation speed: ~80–120 µs per chart.
- Throughput: ~8 000+ charts/sec (multi-threaded).
Releases are automated by GitHub Actions:
-
astro-rust(astronomy library) must be published first: push av2.1.0tag to nimblemo/astro-rust — thePublishworkflow pushes the crate to crates.io. -
In this repository, bump
versioninCargo.toml, refreshCargo.lock(cargo update -p astro-rust), commit, and push a matching tag:git tag v0.5.0 git push origin v0.5.0
-
The
Releaseworkflow then:- verifies the tag matches
Cargo.toml, runs the test suite; - builds ready-to-run binaries for Linux (glibc), macOS (Intel, Apple Silicon) and Windows;
- publishes the binaries with
.sha256checksums and generated release notes to GitHub Releases; - publishes the crate to crates.io.
- verifies the tag matches
The crates.io step requires a CARGO_REGISTRY_TOKEN repository secret (an API token from https://crates.io/settings/tokens). If the version is already published, the step is skipped.
MIT — see LICENSE.