Command Line Interface #

Kerykeion ships a command-line interface that exposes the whole library — every chart type, analytical technique, sky event and factory — without writing any Python. It is a local engine: it computes with the same in-process backend as the library, so it works offline and needs no API key.

The interface is its own package, kerykeion-cli, which the cli extra installs. It is built on the standard library alone, so nothing third-party comes with it:

pip3 install "kerykeion[cli]"  # the library plus the command
uv tool install "kerykeion-cli"  # standalone tool

kerykeion[all] adds the extra and the optional Swiss Ephemeris backend. A plain pip install kerykeion installs the library alone, with no command, and import kerykeion never imports the CLI.

Output formats #

Every command that produces a payload accepts -f/--format and -o/--output:

With no -f, the format is chosen for you: text on a TTY, JSON in a pipe. So kerykeion natal -s ada reads as a report, while kerykeion natal -s ada | jq -r .sun.sign works with no extra flag. -o file infers the format from the suffix unless -f overrides it. When neither -f nor -o is given, $KERYKEION_CLI_FORMAT (one of text, json, xml, svg) sets the default; otherwise the TTY-or-pipe rule applies.

Warnings (ephemeris coverage gaps, polar-house fallbacks) always go to stderr, even with -f json, so a payload piped to jq stays clean. Pass --warnings-as-errors to turn them into exit 9 (after the payload prints).

With -f json, --envelope wraps the payload for consumers that only capture stdout: {kerykeion: {version, backend, generated_at}, warnings: [...], data: {...}}. --envelope is JSON-only and is rejected with any other format.

Subject profiles #

A profile is a small JSON “recipe” (perms 0600 — birth data is PII) stored under $XDG_CONFIG_HOME/kerykeion/subjects/. Save once, reuse everywhere with -s <name>:

$ kerykeion subject save ada --name "Ada Lovelace" --date 1990-07-15 --time 10:30 \
      --lat 41.9028 --lng 12.4964 --tz Europe/Rome --offline
$ kerykeion subject list
$ kerykeion subject show ada
$ kerykeion subject path ada         # the profile's file path (for backup/inspection)
$ kerykeion subject verify ada        # round-trips the recipe through the factory

The same subject-building flags (--date, --time, --lat, --lng, --tz, --zodiac, --houses, --points, --with, --without, --set, …) are spelled identically by subject save, natal and now.

Profiles live under $XDG_CONFIG_HOME/kerykeion/subjects/ (~/.config when XDG_CONFIG_HOME is unset). They are stored as JSON recipes (0600, in a 0700 directory — birth data is personal) and written atomically. A profile is a recipe, never a cached chart: every read rebuilds the subject, so it cannot go stale across kerykeion versions or backends. subject verify rebuilds one and prints a short summary, the cheap pre-flight before a long batch.

Charts #

$ kerykeion natal -s ada -f svg -o /tmp/ada.svg
$ kerykeion synastry -s ada -S bob -f text
$ kerykeion return -s ada --year 2026 --type Solar

Chart appearance #

Every chart command exposes the drawer’s options, so an SVG is not limited to the default look. Values are case-insensitive and an unknown one is exit 4 listing the valid set.

$ kerykeion natal -s ada -f svg -o /tmp/ada.svg --theme dark --chart-language IT
$ kerykeion natal -s ada -f svg -o /tmp/wheel.svg --svg-variant wheel
$ kerykeion natal -s ada -f svg -o /tmp/themed.svg --chart-settings ./palette.json

--chart-settings merges its mapping sections over the library defaults, so overriding one colour does not require restating the palette. --external-view, --degree-indicators and --aspect-icons apply to --style classic only; under the default modern style the library ignores them and says so on stderr.

For -f text, --no-aspects and --max-aspects N shape the report.

Analyses #

$ kerykeion aspects -s ada --aspects trine:6,square
$ kerykeion dominants -s ada --method almuten_figuris
$ kerykeion relationship-score -s ada -S bob

--aspects takes a name or name:orb. Declination aspects use a single --orb instead, and refuse --aspects/--axis-orb-limit, which have no meaning there.

Techniques, sky events and time series #

Curated subcommand groups cover the analytical techniques and astronomical events. Each maps to one factory plus a renderer; their --help is the reference.

$ kerykeion technique profections -s ada
$ kerykeion technique firdaria -s ada
$ kerykeion technique zr -s ada --lot fortune
$ kerykeion technique solar-arc -s ada --target-year 2026
$ kerykeion technique house-comparison -s ada -S bob
$ kerykeion technique fixed-stars -s ada --orb 1.5
$ kerykeion sky eclipses --start-year 2025 --count 5
$ kerykeion sky lunations --from 2026-01-01 --to 2026-12-31
$ kerykeion sky sun-times --from 2026-06-21 --lat 41.9 --lng 12.5 --tz Europe/Rome
$ kerykeion sky mundane --from 2026-01-01 --to 2026-03-01
$ kerykeion sky ingresses --from 2026-01-01 --to 2026-12-31 --periods   # sign stays, not events
$ kerykeion sky phenomena -s ada
$ kerykeion sky occultations -s ada --planet Venus

Time series (ephemeris, transits) sample positions over a range. A pre-flight sampling check fails fast (exit 8) before any heavy computation when a series would exceed the ceiling (730 days / 8760 hours / 525600 minutes); --no-limit disables both the check and the library’s own guard.

$ kerykeion ephemeris --from 2026-01-01 --to 2026-06-30
$ kerykeion transits -s ada --from 2026-01-01 --to 2026-12-31 --events

The call dispatcher #

kerykeion call reaches any public Factory.method (or bare function) in kerykeion.__all__ without a dedicated command. Subject parameters are bound from -s/-S; everything else is --param key=value with type coercion.

$ kerykeion call --list                       # every dispatchable target
$ kerykeion call DominantsFactory.from_subject -s ada
$ kerykeion call ProfectionsFactory.from_subject --explain   # params it accepts
$ kerykeion call ProfectionsFactory.from_subject -s ada \
      --param years_before=2 --param years_after=3

Security is an allowlist. Only names in kerykeion.__all__, split on a single ., no private members. kerykeion call os.system is refused — os is not in __all__:

$ kerykeion call os.system --param cmd=ls
kerykeion: error: 'os' is not in the kerykeion public API; ...

Exit codes #

Errors are one clean line on stderr by default — never a traceback — with the right code. --traceback shows the full traceback (always shown for exit 1).

Discovering values, and checking the install #

The CLI validates against the library’s own literals — 23 house systems, 48 ayanamsas, 11 perspectives, 76 points — and info lists them, read at runtime so they cannot drift from what the flags accept. With -f json it is the source a script should consult instead of hard-coding tables.

$ kerykeion info literals                 # every enum, by name
$ kerykeion info literals SiderealMode    # one of them
$ kerykeion info houses                   # letters and name aliases (case-sensitive)
$ kerykeion info points                   # what --points accepts
$ kerykeion info stars                    # what --fixed-stars accepts
$ kerykeion info methods                  # per-command strategy names

status reports the runtime environment; status --check judges it — the same probes plus a real calculation — and exits 6 when the install is genuinely broken. A widened profile-store mode or a stray ./.env are warnings, not failures.

$ kerykeion status -f json
$ kerykeion status --check

Composite vs Davison #

composite is the midpoint composite only. The library’s Davison time-space-midpoint chart (CompositeSubjectFactory.get_davison_composite_subject_model) has no dedicated command; reach it from the terminal with:

$ kerykeion call CompositeSubjectFactory.get_davison_composite_subject_model -s ada -S bob -f json

Global flags #

--version/-V, --traceback, --warnings-as-errors go before the subcommand: kerykeion --traceback natal -s ada. A bare kerykeion prints help and exits 0.

Manual page #

The kerykeion-cli wheel ships a Unix man page, kerykeion(1), generated from the same command tree behind --help (regenerated in the repository with poe man:generate). Where it lands depends on the install:

For the isolated cases, point the manual path at the prefix once:

man -M "$(uv tool dir)/kerykeion-cli/share/man" kerykeion   # a one-off read
export MANPATH="$HOME/.local/share/uv/tools/kerykeion-cli/share/man:$MANPATH"  # or in the profile

The page is the map — the command tree, the output formats, the profile store, the environment, the exit codes — while each command’s flags remain one kerykeion <command> --help away. Technique, sky and time-series commands (technique …, sky …, ephemeris, transits) expose their full flag tables only there; see also the tested recipes in the CLI Agent Skill.