Kerykeion CLI

Driving Kerykeion from the terminal

Verified against kerykeion 6.0.1, Python 3.12+.

The CLI ships as an optional extra. Everything the library computes is reachable from the shell: about fifty curated commands, plus kerykeion call as a guarded dispatcher over the rest of the public API.

Accuracy rule for you: never invent a flag or a value. The CLI describes itself — kerykeion info literals -f json lists every accepted value, and kerykeion call <Factory>.<method> --explain describes every parameter. Read those instead of guessing; the tables are large (48 ayanamsas, 23 house systems, 76 points) and change between releases.

Install

# gate: skip
pip install "kerykeion[cli]==6.0.1"
# Or: uv tool install "kerykeion-cli==6.0.1"

The command lives in its own package, kerykeion-cli, which the extra installs; a plain pip install kerykeion has the library and no command. The interface is built on the standard library alone, so nothing third-party comes with it. kerykeion status is always safe to run first.

The three rules that keep output usable

1. The payload goes to stdout; warnings and notes always go to stderr. This holds for every format, including JSON. Never parse stderr, and never assume a clean stderr means success — check the exit code.
2. Format follows the destination: a terminal gets text, a pipe gets JSON. Force it with -f text|json|xml|svg, or let -o out.svg infer from the suffix. Scripts should pass -f explicitly rather than rely on the default. JSON is the library's full model (a natal chart is ~35 KB); -f xml is to_context(), the same chart in ~5 KB, and the shape to read into a context window. -f is the one format flag, on every command.
3. Exit codes are the contract. Branch on them; do not match on messages.

kerykeion subject save ada --name "Ada Lovelace" \
  --date 1815-12-10 --time 18:00 \
  --lat 51.5074 --lng -0.1278 --tz Europe/London --offline

kerykeion natal -s ada -f json | head -3        # JSON, no ANSI, clean to pipe
kerykeion natal -s ada -f svg -o /tmp/ada.svg   # SVG to a file

If a consumer cannot read stderr, --envelope puts provenance and the warnings in the JSON itself. Every command that produces a payload takes it:

kerykeion natal -s ada -f json --envelope

Exit codes

kerykeion status --check runs the install checks and exits 6 when the install is genuinely broken; a plain kerykeion status only reports and always exits 0.

kerykeion status --check -f json

Subjects live in profiles

Almost every command takes -s <profile> rather than fifteen inline flags. A profile is a JSON recipe stored under $XDG_CONFIG_HOME/kerykeion/subjects/, written 0600 inside a 0700 directory because birth data is personal.

kerykeion subject list
kerykeion subject show ada -f json
kerykeion subject verify ada -f json

Inline flags override the profile, so a stored subject can be reused for a relocated reading without editing it. Full details and --set: references/profiles.md.

Capability routing — find the command, then open the reference

Top traps

These produce a wrong chart silently or a confusing failure. They are the reason to read before composing a command.

• House-system letters are case-sensitive. i (Sunshine/alt.) and I (Sunshine) are different systems. --houses placidus (a name) is safer than a letter; kerykeion info houses lists both.
• A relocated transit/return takes either --lat/--lng/--tz together or --city (geocoded; needs the network or the local default-geo database). Two coordinates out of three is exit 4, on purpose: the natal timezone at new coordinates is a multi-hour error in the houses and Ascendant. Passing both --city and coordinates is also exit 4 — one command, one place, never a silent pick between the two.
• --online and --offline are mutually exclusive (exit 4). Prefer --offline in scripts; the default goes online only when lat/lng/tz are not all known.
• sky voc --from/--to is a UTC range. Pass --tz (or a profile) so naive bounds are read in that zone rather than as UTC.
• An offset-bearing --from on a DST fall-back hour is refused rather than guessed, because the moment factories take wall-clock parts without a fold.
• transits --refine requires --events. Alone it would be a silent no-op.
• transits --include-subjects is for per-sample moments, not --events. Add --calculate-dignities when those attached subjects also need essential dignity fields; on transits, it requires --include-subjects.
• A long series hits the sampling ceiling (exit 8) before computing anything. Widen the step or pass --no-limit deliberately.
• Chart flags --degree-indicators, --aspect-icons and --external-view only apply to --style classic. Under the default modern style the library ignores them and says so on stderr.

Never invent values

kerykeion info literals -f json | head -5      # every accepted enum, by name
kerykeion info houses                           # letters and name aliases
kerykeion info points                           # what --points accepts
kerykeion info methods                          # strategy names per command

Reference index

• references/commands.md — the whole command tree, with what each one needs.
• references/io-and-exit-codes.md — formats, streams, --envelope, exit codes, info, status --check.
• references/profiles.md — the profile store, --set, permissions and PII.
• references/rendering.md — every SVG and report option, and which chart types they affect.
• references/call-dispatcher.md — reaching any public factory, --explain, and --param coercion.
• references/recipes.md — task-shaped examples for pipelines, batches and CI.

For writing Python against the library rather than driving it from a shell, use the kerykeion skill instead.