Skip to content

CLI Reference

koryph — central multi-project orchestrator for autonomous AI coding agents.

Quick index

Command Summary
koryph init create ~/.koryph, verify tools on PATH, print next steps
koryph project onboard and manage registered projects
↳ koryph project add register a project (inspect + register + scaffold adapter + install assets)
↳ koryph project install-assets (re)install koryph assets — agents, commands, and rules
↳ koryph project list list managed projects (id, account, status, root)
↳ koryph project show print one project record as JSON
↳ koryph project set-account change a project's account (audited; resets validation)
↳ koryph project set-runtime-account enroll one runtime's account (audited; resets validation)
koryph validate run the pre-dispatch gate
koryph run execute one engine run over a project
koryph intake poll external issue trackers into planning beads
koryph nudge record an operator note for a running or capability-blocked phase
koryph stop stop an agent (or every agent with --all)
koryph drain gracefully wind down a run: finish active slots, dispatch nothing new
koryph resize live width override for a running loop
koryph merge merge a worktree branch by name (push/squash/keep-worktree)
koryph land land an engine-opened PR by bead id, fast-forward-only
koryph review-pr analyze another author's PR
koryph pr-sync reconcile pr-opened beads against live PR state
koryph bot provision and manage koryph GitHub App bots
↳ koryph bot create create a GitHub App via the manifest flow (one browser click)
↳ koryph bot install print/open the installation page for a provisioned bot
↳ koryph bot attach wire a repo to a bot: set secrets and enable Actions PR-approval toggle
↳ koryph bot list list provisioned bots in ~/.koryph/bots/
↳ koryph bot check run the bot validator chain (JWT, installation, secrets, Actions toggle)
↳ koryph bot vault-migrate move a plaintext bot private key into a vault or encrypted file
koryph signing configure and operate vault-backed commit signing
↳ koryph signing setup write the signing policy into the adapter
↳ koryph signing enable load the key + apply repo git config
↳ koryph signing keygen generate a passphrase-protected SSH signing key (no-vault path)
↳ koryph signing status mode/provider/agent-ready summary
↳ koryph signing verify verify branch commit signatures
koryph sign cosign sign-blob an artifact via the vault key
koryph release configure and operate the project release pipeline
↳ koryph release setup render and install release workflow + release-please config
↳ koryph release kick close+reopen the Release PR so checks fire under your gh auth
koryph board one-line-per-project run overview
koryph roster per-bead titled roster grouped by lifecycle
koryph status latest-run per-slot detail
koryph tail tail a phase's session.log + stderr.log
koryph doctor health check: layout, binaries, registry, governor
koryph plan deterministic corpus conflict analysis and scoped epic quality gate
koryph governor inspect and set the machine-wide concurrency cap
↳ koryph governor show show the cap, active leases, and demand
↳ koryph governor set set the machine-wide cap
↳ koryph governor set-resource configure or remove a machine resource kind (kind-cluster, docker, ...)
koryph quota per-account governor snapshot
↳ koryph quota calibrate calibrate a governor ceiling from an observed /usage reading
↳ koryph quota guard live billing-guard toggle — on|advisory|off [--until ]; re-read each wave without a restart
↳ koryph quota set-threads set (or clear with 0) this account's persisted default concurrency-pool seed
↳ koryph quota set-rolling set (or clear with 0) an api-key account's rolling-$ governor ceiling (USD)
koryph metrics burn + reliability rollup across projects
↳ koryph metrics estimator per-(model,size) estimator accuracy stats
↳ koryph metrics tokens per-bead and per-tier token composition, cache-hit ratio, and tokens-per-bead trend
↳ koryph metrics autonomy inspect or explicitly publish fixed-cohort autonomy SLO evidence
koryph repo check or apply .github IaC (rulesets, repo settings)
↳ koryph repo describe explain every setting in .github IaC and why
↳ koryph repo check diff live GitHub settings/rulesets against .github IaC (exit 1 on drift)
↳ koryph repo apply apply .github IaC (rulesets, repo settings) to the live repo
↳ koryph repo rollback roll back to a pre-apply snapshot
koryph posture apply a named desired-state profile to a GitHub repo
↳ koryph posture list list built-in and user-defined profiles
↳ koryph posture describe explain every setting a profile enforces and why
↳ koryph posture check diff live GitHub state against a profile (exit 1 on drift, or 0 with --no-fail)
↳ koryph posture diff deprecated alias for check --no-fail (always exit 0)
↳ koryph posture apply show diff then apply a profile to the live GitHub repo
↳ koryph posture rollback roll back to a pre-apply snapshot (alias for repo rollback)
koryph onboard read-only inventory of a project
koryph batch submit a Message Batch (explicit per-token spend)
↳ koryph batch run submit a batch from a JSONL file
koryph version print the engine version
koryph completion print or install a shell completion script
↳ koryph completion bash print the bash completion script
↳ koryph completion zsh print the zsh completion script
↳ koryph completion install install the completion script to the standard location
koryph adopt wizard: take an existing repo to a green koryph validate in one run
koryph ci render and install forge-native CI pipeline assets
↳ koryph ci setup render and install CI assets into the project
↳ koryph ci check report drift between installed CI assets and current Render output
koryph cockpit emit a cockpit snapshot for the VS Code extension
koryph dns reconcile narrowly scoped DNS records for hosted pages
↳ koryph dns github-pages reconcile Cloudflare DNS-only records for a GitHub Pages domain
koryph epic on-demand epic validation: completeness + structural health review
koryph gc apply data lifecycle policy: compress old run dirs, rotate audit logs
koryph inject add a bead to a running loop even if it is outside the run's scope
koryph loop run the binary-native autonomous supervisor
koryph models recommend (and --apply) learned model tiers from escalation history
koryph obs manage observability: status, level, enable, disable, tail, export, prune
↳ koryph obs status print current observability configuration
↳ koryph obs level set the log level for a component (or default)
↳ koryph obs enable enable observability (set default level to info)
↳ koryph obs disable silence all output (set all levels to error)
↳ koryph obs tail tail the telemetry JSONL stream in human-readable form
↳ koryph obs export bundle one run's telemetry as redaction-verified JSONL
↳ koryph obs prune remove telemetry files older than the retention window
koryph ops dispatch-free operator maintenance (reconcile dead runs)
↳ koryph ops reconcile park zombie slots of a dead run blocked, release their leases, finalize the run
koryph phase request orchestrator-owned actions from the current worker phase
↳ koryph phase request submit a typed phase request
↳ koryph phase block report a structured capability block
↳ koryph phase complete write the SHA-bound terminal candidate result
koryph tui interactive terminal cockpit (threads, queue, events)

koryph init

create ~/.koryph, verify tools on PATH, print next steps

See also: Installation · Quickstart

No flags.

koryph project

onboard and manage registered projects

See also: Projects and accounts · Accounts

Run koryph project <subcommand> -h for subcommand flags.

koryph project add

register a project (inspect + register + scaffold adapter + install assets)

See also: Projects and accounts · Zero to shipped

Flag Type Default Description
--account string account profile: personal|work (required)
--auth-mode string auth mode: subscription (default; OAuth login) | api-key (long-lived ANTHROPIC_API_KEY; bills PAY-PER-TOKEN, not the subscription; requires --credential-) | oauth-token (long-lived CLAUDE_CODE_OAUTH_TOKEN; subscription-billed; requires --credential-)
--branch string default branch (default: detected)
--config-dir string runtime config directory (CLAUDE_CONFIG_DIR for Claude; CODEX_HOME for Codex)
--credential-env string purpose-named env var holding the credential (with --credential-source env; must not be ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN)
--credential-provider string vault provider name (with --credential-source vault)
--credential-ref string vault item reference/name (with --credential-source vault)
--credential-source string credential source for --auth-mode api-key|oauth-token: vault|env
--force bool override an .envrc account-disagreement refusal
--id string project slug (default: repo dir name slugified)
--identity string runtime identity that must match at dispatch, or auto to detect it locally (required)
--name string display name (default: project id)
--no-posture bool skip the posture profile offer entirely
--posture string posture profile to apply non-interactively (e.g. oss-solo-maintainer); skips the interactive prompt
--runtime string claude initial runtime name (claude or codex)

koryph project install-assets

(re)install koryph assets — agents, commands, and rules

See also: Projects and accounts

Flag Type Default Description
--all bool install into every registered project (registry-wide refresh)
--all-projects bool deprecated alias for --all
--force bool overwrite existing assets whose content differs

koryph project list

list managed projects (id, account, status, root)

See also: Projects and accounts

Flag Type Default Description
--json bool emit JSON array of project records

koryph project show

print one project record as JSON

See also: Projects and accounts

Flag Type Default Description
--project string project id (alternative to positional ; default: the project containing the current directory)

koryph project set-account

change a project's account (audited; resets validation)

See also: Projects and accounts · Accounts

Flag Type Default Description
--config-dir string CLAUDE_CONFIG_DIR for the new account
--identity string new expected login email (required)
--profile string new account profile: personal|work (required)
--project string project id (alternative to positional ; default: the project containing the current directory)
--reason string why the account is changing (required, audited)

koryph project set-runtime-account

enroll one runtime's account (audited; resets validation)

See also: Projects and accounts · Runtimes

Flag Type Default Description
--config-dir string runtime config directory (CODEX_HOME for Codex)
--default bool also select this runtime as the project's default_runtime
--identity string verified runtime identity, or auto to detect it locally (required)
--project string project id (alternative to positional ; default: the project containing the current directory)
--reason string why the runtime account is changing (required, audited)
--runtime string runtime name (required, for example codex)

koryph validate

run the pre-dispatch gate

See also: Projects and accounts · Zero to shipped

Flag Type Default Description
--project string project id (alternative to positional ; default: the project containing the current directory)

koryph run

execute one engine run over a project

See also: Running waves · Rolling dispatch · Beads

Flag Type Default Description
--allow-api-spend bool permit api-key billing at governor stop
--allow-unvalidated bool permit runs on non-validated projects
--auto-merge bool allow auto-merge for merge:auto items
--budget float64 per-run cost ceiling in USD (0 = unlimited)
--default-model string model for label-less beads
--direct bool owner override: skip PRs and merge straight to the default branch (needs branch-protection bypass)
--dispatch-mode string dispatch mode: wave|rolling (default: project config, else wave)
--dry-run bool plan and print without dispatching
--manual bool single manual dispatch semantics (quota-exempt)
--max int wave width cap (0 = project/engine default)
--no-billing-guard bool disable quota throttling for this run (usage still measured; billing stays subscription)
--once bool run exactly one wave
--only string dispatch only this specific ready bead id
--parent string epic scope for the bd frontier
--project string project id (default: the project containing the current directory)
--require-calibration bool refuse to dispatch while the quota governor is uncalibrated (koryph-grz); run 'koryph quota calibrate' first
--resume bool classify and re-dispatch the latest run first
--review bool post-implementation review pass before merge
--runtime-equivalent string force this runtime using equivalent model capability mappings
--runtime-only string dispatch only beads normally routed to this runtime

koryph intake

poll external issue trackers into planning beads

See also: Intake · Beads

Flag Type Default Description
--comment bool comment the bead id back on each ingested issue
--dry-run bool print what would be ingested; mutate nothing
--label string trigger label to poll (overrides per-source config; default "triage")
--limit int max open issues to poll (overrides per-source config; default 20)
--project string project id (default: the project containing the current directory)

koryph nudge

record an operator note for a running or capability-blocked phase

See also: Running waves

Flag Type Default Description
--project string project id (default: the project containing the current directory)

koryph stop

stop an agent (or every agent with --all)

See also: Running waves

Flag Type Default Description
--all bool stop every active agent — across ALL managed projects, or one project with --project
--force bool SIGKILL instead of SIGTERM — uncommitted worktree work is LOST
--project string project id (default: the project containing the current directory; unless --all)

koryph drain

gracefully wind down a run: finish active slots, dispatch nothing new

See also: Running waves · Rolling dispatch

Flag Type Default Description
--all bool request a drain for every registered project
--project string project id (default: the project containing the current directory; unless --all)

koryph resize

live width override for a running loop

See also: Running waves · Governors

Flag Type Default Description
--all bool apply to every registered project
--clear bool remove the width override (revert to project config)
--force bool allow --max to exceed the project's max_concurrent_slots
--max int new width cap (must be > 0; use --clear to remove an override)
--project string project id (default: the project containing the current directory; unless --all)

koryph merge

merge a worktree branch by name (push/squash/keep-worktree)

See also: Running waves · Worktrees

Flag Type Default Description
--allow-protected bool lift the routine CI/build protected paths (.github/, Makefile) for this merge; governance defaults and project protected_paths still refuse
--close-bead string bead to close on a successful merge
--keep-worktree bool keep the worktree + branch after merge
--project string project id (default: the project containing the current directory)
--push bool push the default branch after merge
--reason string close reason for --close-bead
--squash bool squash-merge instead of ff-only
--wait bool wait (with periodic progress) for a live engine run on this project to release the project lock, instead of failing fast

koryph land

land an engine-opened PR by bead id, fast-forward-only

See also: Running waves · Worktrees

Flag Type Default Description
--allow-protected bool lift the routine CI/build protected paths (.github/, Makefile) for this landing; governance defaults and project protected_paths still refuse
--method string landing method override: ff|squash (default: project merge_method, else ff)
--project string project id (default: the project containing the current directory)
--reason string bead close reason
--wait bool wait (with periodic progress) for a live engine run on this project to release the project lock, instead of failing fast

koryph review-pr

analyze another author's PR

See also: Running waves · Collaboration

Flag Type Default Description
--all bool analyze every open PR in the queue (skips drafts and PRs you authored)
--approve bool register an approving review (your explicit instruction — koryph never approves autonomously)
--body string review/approval body, or the --close comment
--close bool close the PR (optionally with --body as the comment)
--comment bool post koryph's line-anchored findings as inline PR comments
--comment-on multi post an inline comment: 'path:line:message' (repeatable)
--project string project id (default: the project containing the current directory)
--resume bool re-display the saved analysis for a PR (after an IDE handoff)

koryph pr-sync

reconcile pr-opened beads against live PR state

See also: Running waves

Flag Type Default Description
--project string project id (default: the project containing the current directory)

koryph bot

provision and manage koryph GitHub App bots

See also: Release train · Release bot

Run koryph bot <subcommand> -h for subcommand flags.

koryph bot create

create a GitHub App via the manifest flow (one browser click)

See also: Release bot

Flag Type Default Description
--headless bool print the URL instead of opening the browser (set automatically when TERM is unset)
--key-ref string provider-specific reference for the key (e.g. pass:// URI, op:// ref, or file path); auto-derived when omitted
--name string GitHub App name (e.g. mylogin-release-bot); defaults to -release-bot when omitted (requires gh CLI)
--org string create the app under this GitHub organization (omit for personal account)
--plaintext bool store the private key inline as plaintext PEM (legacy; prefer a vault or encrypted-file provider)
--provider string vault provider for the private key (protonpass|onepassword|encrypted-file|keychain|file|…); auto-selects when omitted
--public bool make the app publicly installable (required for guest-org repo-admin installs)
--vault-provider string deprecated alias for --provider

koryph bot install

print/open the installation page for a provisioned bot

See also: Release bot

Flag Type Default Description
--name string bot name (required)

koryph bot attach

wire a repo to a bot: set secrets and enable Actions PR-approval toggle

See also: Release bot

Flag Type Default Description
--name string bot name (required)
--org-secrets bool set secrets at org level with selected-repos visibility instead of per-repo
--repo string GitHub repository as OWNER/REPO (required)

koryph bot list

list provisioned bots in ~/.koryph/bots/

See also: Release bot

Flag Type Default Description
--check bool perform a live GET /app identity check for each bot

koryph bot check

run the bot validator chain (JWT, installation, secrets, Actions toggle)

See also: Release bot

Flag Type Default Description
--name string bot name (required)
--repo string GitHub repository as OWNER/REPO (optional; adds repo-scoped validators)

koryph bot vault-migrate

move a plaintext bot private key into a vault or encrypted file

See also: Signing · Release bot

Flag Type Default Description
--key-ref string provider-specific key reference (auto-derived when omitted)
--name string bot name (required)
--provider string destination vault provider (auto-selected when omitted)
--vault-provider string deprecated alias for --provider

koryph signing

configure and operate vault-backed commit signing

See also: Signing · Postures

Run koryph signing <subcommand> -h for subcommand flags.

koryph signing setup

write the signing policy into the adapter

See also: Signing

Flag Type Default Description
--artifacts bool enable cosign blob signing (koryph sign blob)
--identity string signer email (required)
--item-title string item title for public-key resolution via view_by_title template (requires --vault-name)
--key-ref string vault item URI / file path for the signing key (also used for public-key resolution when no --public-key or --vault-name/--item-title is given)
--mode string ssh signing mode: ssh|gitsign
--project string project id (required)
--provider string vault provider: protonpass|onepassword|file|command
--public-key string SSH public key: literal ("ssh-ed25519 AAAA...") or "@" to read from file
--vault-name string vault name for public-key resolution via view_by_title template

koryph signing enable

load the key + apply repo git config

See also: Signing

Flag Type Default Description
--project string project id (default: the project containing the current directory)

koryph signing keygen

generate a passphrase-protected SSH signing key (no-vault path)

See also: Signing

Flag Type Default Description
--identity string key comment / signer identity (default: @)
--key-ref string path to store the key (default: ~/.koryph/signing/.key)
--project string project id (used to resolve existing config; optional)
--provider string vault provider: keychain|encrypted-file|file (default: platform best)

koryph signing status

mode/provider/agent-ready summary

See also: Signing

Flag Type Default Description
--json bool emit JSON
--project string project id (default: the project containing the current directory)

koryph signing verify

verify branch commit signatures

See also: Signing

Flag Type Default Description
--branch string branch to verify against the default branch (required)
--project string project id (default: the project containing the current directory)

koryph sign

cosign sign-blob an artifact via the vault key

See also: Signing · Supply chain

Flag Type Default Description
--project string project id (default: the project containing the current directory)

koryph release

configure and operate the project release pipeline

See also: Release train · Releasing projects

Run koryph release <subcommand> -h for subcommand flags.

koryph release setup

render and install release workflow + release-please config

See also: Release train · Releasing projects

Flag Type Default Description
--bot bool run scripts/provision-release-bot.sh --attach after setup
--mode string build mode: goreleaser (mode A) or commands (mode B); required when the project has no release block yet
--project string project id (default: the project containing the current directory)
--version string 0.0.0 initial version for the release-please manifest (only used when the manifest does not yet exist)

koryph release kick

close+reopen the Release PR so checks fire under your gh auth

See also: Release train · Releasing projects

Flag Type Default Description
--pr int explicit PR number (skips auto-detect)
--repo string owner/repo GitHub slug (required)
--wait bool poll check conclusions after reopening
--wait-timeout string 10m max wait duration (e.g. 10m, 30m)

koryph board

one-line-per-project run overview

See also: Running waves

Flag Type Default Description
--json bool emit the board as JSON

koryph roster

per-bead titled roster grouped by lifecycle

See also: Running waves · Beads

Flag Type Default Description
--json bool emit roster as JSON
--project string project id (default: the project containing the current directory)
--run string run id (default: latest)

koryph status

latest-run per-slot detail

See also: Running waves

Flag Type Default Description
--frontier bool show the last wave's per-candidate dispatch verdict instead of the slot table
--json bool emit the run as JSON
--project string project id (default: the project containing the current directory)

koryph tail

tail a phase's session.log + stderr.log

See also: Running waves

Flag Type Default Description
--follow bool stream new lines as they appear (Ctrl-C to stop)
--n int 40 number of trailing lines
--project string project id (default: the project containing the current directory)

koryph doctor

health check: layout, binaries, registry, governor

See also: Doctor

Flag Type Default Description
--autonomy-canary bool require valid passing fixed-cohort autonomy release evidence
--fix bool auto-remediate: remove zombie slots/stale demand (global); install missing assets (project)
--force bool with --fix and --project: also overwrite stale asset files (default: only install missing)
--json bool emit the report as JSON instead of a table
--matrix bool render the integration matrix for the project at --root (or current dir)
--project string run project-scoped checks for the named project
--root string . project repository root for --matrix mode

koryph plan

deterministic corpus conflict analysis and scoped epic quality gate

See also: Beads · Footprints

Flag Type Default Description
--epic string scope analysis and quality checks to one epic
--json bool emit the audit report as JSON (for agent consumption)
--project string project id (default: the project containing the current directory)
--strict bool exit non-zero when the scoped epic has quality or scheduling errors

koryph governor

inspect and set the machine-wide concurrency cap

See also: Governors · Billing and quota · Global governor

Flag Type Default Description
--json bool emit JSON array of pool snapshots

koryph governor show

show the cap, active leases, and demand

See also: Governors

koryph governor set

set the machine-wide cap

See also: Governors · Global governor

Flag Type Default Description
--account string account whose per-account concurrency pool to configure (koryph-1o2.1): the pool is keyed on the resolved account (e.g. "personal", "work"), so a larger subscription can run more agents than a smaller seat. Wins over --provider when both are given; omit both for the default "anthropic" pool
--adaptive bool enable the AIMD overlay: probe the cap up on quiet, halve it on rate-limit
--break-sec int circuit breaker base open duration, under --adaptive (default 300, doubles per re-open, cap 3600)
--est-per-agent-mb int per-agent memory reservation for beads with NO res: footprint (koryph-3xs): the memory gate subtracts N MB per kind-less agent so K of them reserve K*N against the floor. 0 = the conservative default (1536); a negative value disables the reservation. May be set alone or alongside --max-global
--hard-max int absolute ceiling for upward probing under --adaptive (default 2x --max-global)
--machine-ceiling int machine-wide ceiling on TOTAL concurrent agents across ALL pools (koryph-4rk6.2, > 0): bounds the sum of per-pool caps so independent pools cannot jointly sink the host. Machine-scoped, not per-pool — ignores --account/--provider; may be set alone. Absent/unset uses the default (8)
--max-global int cap on concurrently running agents in this pool (required, > 0)
--min-dispatch-interval int minimum inter-dispatch spacing in seconds, under --adaptive (default 3, jittered ±50%)
--min-free-memory-mb int memory admission floor (koryph-930): defer new agents while host available memory is below N MB. 0 = auto-size to physical memory (the default; the gate is ON); a negative value disables the gate. May be set alone or alongside --max-global
--provider string governor pool to configure by raw pool key (default: anthropic) — koryph-v8u.11 independent pools; prefer --account
--settle-sec int settle window after any cap change, under --adaptive (default 120)

koryph governor set-resource

configure or remove a machine resource kind (kind-cluster, docker, ...)

See also: Governors · Global governor

Flag Type Default Description
--capacity int max concurrent holders of this kind across all pools (<=0 resolves to the fail-safe default of 1)
--mem-mb int per-holder memory reservation in MB during the ramp window (0 = uncalibrated, no reservation)
--probe string leak-detection shell command listing live instance names (patrol/doctor only — never consulted on the admission path)
--ramp-seconds int ramp window in seconds before a holder's reservation is assumed materialized (<=0 = machine/global default)
--unset bool remove this kind from the resources ledger (must be the only flag)

koryph quota

per-account governor snapshot

See also: Governors · Billing and quota

Flag Type Default Description
--account string limit to one account (default: all across records)
--json bool emit JSON

koryph quota calibrate

calibrate a governor ceiling from an observed /usage reading

See also: Governors · Billing and quota

Flag Type Default Description
--account string account to calibrate (required)
--observed-pct float64 observed /usage percentage
--observed-usd float64 observed ccusage spend (USD)
--plan-tier string plan tier label (e.g. max20x)
--window string window to calibrate: 5h|weekly (required)

koryph quota guard

live billing-guard toggle — on|advisory|off [--until ]; re-read each wave without a restart

See also: Billing and quota · Governors

Flag Type Default Description
--account string account to configure (required)
--until string auto-revert duration from now (e.g. 2h, 24h); omit for permanent

koryph quota set-threads

set (or clear with 0) this account's persisted default concurrency-pool seed

See also: Billing and quota · Governors

Flag Type Default Description
--account string account to configure (required)

koryph quota set-rolling

set (or clear with 0) an api-key account's rolling-$ governor ceiling (USD)

See also: Billing and quota · Governors

Flag Type Default Description
--account string account to configure (required)

koryph metrics

burn + reliability rollup across projects

See also: Billing and quota · Governors

Flag Type Default Description
--json bool emit JSON
--project string limit to one project

koryph metrics estimator

per-(model,size) estimator accuracy stats

See also: Billing and quota

Flag Type Default Description
--account string limit to one account
--json bool emit JSON

koryph metrics tokens

per-bead and per-tier token composition, cache-hit ratio, and tokens-per-bead trend

See also: Billing and quota

Flag Type Default Description
--experiment bool render the L6 two-arm (proxied vs holdout) standing-canary comparison instead
--json bool emit JSON
--project string limit to one project ID

koryph metrics autonomy

inspect or explicitly publish fixed-cohort autonomy SLO evidence

See also: Autonomy slos

Flag Type Default Description
--input string schema-versioned canary evidence input
--json bool also emit the complete report as JSON
--out string offline-autonomy-diagnostic.json offline immutable report path (native fixed path is reserved)
--project string inspect the native report for this project

koryph repo

check or apply .github IaC (rulesets, repo settings)

See also: Postures · Ejectability

Run koryph repo <subcommand> -h for subcommand flags.

koryph repo describe

explain every setting in .github IaC and why

See also: Postures

Flag Type Default Description
--repo string repository in owner/name form — when given, shows live value per setting

koryph repo check

diff live GitHub settings/rulesets against .github IaC (exit 1 on drift)

See also: Postures · Ejectability

Flag Type Default Description
--repo string repository in owner/name form (default: detected from git remote via gh)

koryph repo apply

apply .github IaC (rulesets, repo settings) to the live repo

See also: Postures · Ejectability

Flag Type Default Description
--repo string repository in owner/name form (default: detected from git remote via gh)

koryph repo rollback

roll back to a pre-apply snapshot

See also: Postures

Flag Type Default Description
--repo string repository in owner/name form (default: detected from git remote via gh)
--to string latest snapshot selector: "latest" or a RFC3339 timestamp (or prefix, e.g. "2026-07-04T16")

koryph posture

apply a named desired-state profile to a GitHub repo

See also: Postures · Postures

Run koryph posture <subcommand> -h for subcommand flags.

koryph posture list

list built-in and user-defined profiles

See also: Postures

Flag Type Default Description
--fragments bool list built-in security-scanner fragments instead of profiles

koryph posture describe

explain every setting a profile enforces and why

See also: Postures · Postures

Flag Type Default Description
--param multi profile parameter as key=value (repeatable, e.g. --param required_checks="pre-commit,make gate")
--repo string repository in owner/name form — when given, shows live value per setting

koryph posture check

diff live GitHub state against a profile (exit 1 on drift, or 0 with --no-fail)

See also: Postures · Postures

Flag Type Default Description
--force bool with apply: overwrite stale fragment files (default: only install missing fragments)
--no-fail bool always exit 0, even when drift is found (informational; same as posture diff)
--org string GitHub organisation for org-level ruleset check/apply (requires org owner/admin)
--param multi profile parameter as key=value (repeatable, e.g. --param required_checks="pre-commit,make gate")
--repo string repository in owner/name form (default: detected from git remote via gh)

koryph posture diff

deprecated alias for check --no-fail (always exit 0)

See also: Postures · Postures

Flag Type Default Description
--force bool with apply: overwrite stale fragment files (default: only install missing fragments)
--no-fail bool true always exit 0, even when drift is found (informational; same as posture diff)
--org string GitHub organisation for org-level ruleset check/apply (requires org owner/admin)
--param multi profile parameter as key=value (repeatable, e.g. --param required_checks="pre-commit,make gate")
--repo string repository in owner/name form (default: detected from git remote via gh)

koryph posture apply

show diff then apply a profile to the live GitHub repo

See also: Postures · Postures

Flag Type Default Description
--force bool with apply: overwrite stale fragment files (default: only install missing fragments)
--org string GitHub organisation for org-level ruleset check/apply (requires org owner/admin)
--param multi profile parameter as key=value (repeatable, e.g. --param required_checks="pre-commit,make gate")
--repo string repository in owner/name form (default: detected from git remote via gh)

koryph posture rollback

roll back to a pre-apply snapshot (alias for repo rollback)

See also: Postures

Flag Type Default Description
--repo string repository in owner/name form (default: detected from git remote via gh)
--to string latest snapshot selector: "latest" or a RFC3339 timestamp (or prefix, e.g. "2026-07-04T16")

koryph onboard

read-only inventory of a project

See also: Projects and accounts · Architecture

Flag Type Default Description
--json bool emit the inventory as JSON

koryph batch

submit a Message Batch (explicit per-token spend)

See also: Billing and quota

Run koryph batch <subcommand> -h for subcommand flags.

koryph batch run

submit a batch from a JSONL file

See also: Billing and quota

Flag Type Default Description
--cache-prefix bool apply a 1h cache breakpoint to the shared system prefix (default from --project's prompt_cache_policy)
--input string JSONL input file with {id,system,user} lines (required)
--key-env string env var NAME holding the API key (required; never ANTHROPIC_API_KEY)
--max-tokens int max output tokens per request (default 4096)
--model string model tier: haiku|sonnet|opus|fable (required)
--out string results JSONL destination (default stdout)
--project string registered project ID whose prompt_cache_policy defaults --cache-prefix
--yes bool confirm the estimated spend and submit

koryph version

print the engine version

No flags.

koryph completion

print or install a shell completion script

See also: Installation

Run koryph completion <subcommand> -h for subcommand flags.

koryph completion bash

print the bash completion script

See also: Installation

koryph completion zsh

print the zsh completion script

See also: Installation

koryph completion install

install the completion script to the standard location

See also: Installation

Flag Type Default Description
--shell string target shell: bash|zsh (default: detect from $SHELL)

koryph adopt

wizard: take an existing repo to a green koryph validate in one run

See also: Adopt · Quickstart

Flag Type Default Description
--account string account profile (with --identity; overrides discovery)
--auth-mode string auth mode: subscription (default; OAuth login) | api-key (long-lived ANTHROPIC_API_KEY; bills PAY-PER-TOKEN, not the subscription; requires --credential-) | oauth-token (long-lived CLAUDE_CODE_OAUTH_TOKEN; subscription-billed; requires --credential-)
--branch string default branch (default: detected)
--config-dir string runtime config directory (CLAUDE_CONFIG_DIR for Claude; CODEX_HOME for Codex)
--credential-env string purpose-named env var holding the credential (with --credential-source env; must not be ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN)
--credential-provider string vault provider name (with --credential-source vault)
--credential-ref string vault item reference/name (with --credential-source vault)
--credential-source string credential source for --auth-mode api-key|oauth-token: vault|env
--dry-run bool detect + print the adoption plan, write nothing
--force bool override an .envrc account-disagreement refusal
--forge string forge provider github|gitlab (overrides inference)
--gate gate gate command (repeatable, or one ";;"-separated list); overrides inference
--id string project slug (default: repo dir name slugified)
--identity string runtime identity that must match at dispatch, or auto to detect it locally (with --account)
--json bool emit the plan (and results) as JSON on stdout; implies non-interactive
--no-commit bool skip the adoption commit offer
--no-posture bool skip the posture profile offer
--no-remote bool force a local-only beads init (no sync remote)
--remote string beads sync remote URL (overrides the derived origin)
--runtime string agent runtime (claude or codex; defaults to the existing project or claude)
--yes bool non-interactive: accept unambiguous derivations, fail closed on ambiguity

koryph ci

render and install forge-native CI pipeline assets

See also: Ci setup

Run koryph ci <subcommand> -h for subcommand flags.

koryph ci setup

render and install CI assets into the project

See also: Ci setup

Flag Type Default Description
--gate-cmd string override the gate command (default: make gate)
--kind string gate CI asset kind(s) to install: gate, scanner, docs, or all
--project string project id

koryph ci check

report drift between installed CI assets and current Render output

See also: Ci setup

Flag Type Default Description
--gate-cmd string override the gate command (default: make gate)
--kind string gate CI asset kind(s) to check: gate, scanner, docs, or all
--project string project id

koryph cockpit

emit a cockpit snapshot for the VS Code extension

See also: Ide setup

Flag Type Default Description
--json bool emit snapshot as JSON (used by the VS Code extension)
--project string project id (required)

koryph dns

reconcile narrowly scoped DNS records for hosted pages

See also: Github pages

Run koryph dns <subcommand> -h for subcommand flags.

koryph dns github-pages

reconcile Cloudflare DNS-only records for a GitHub Pages domain

See also: Github pages

Flag Type Default Description
--domain string apex custom domain to configure (for example, docs.example.com)
--pages-domain string GitHub Pages default domain (for example, owner.github.io)
--project string project id
--vault-provider string vault provider for --vault-ref (uses the project/global fallback ladder when omitted)
--vault-ref string reference to the scoped Cloudflare API token in the selected vault

koryph epic

on-demand epic validation: completeness + structural health review

See also: Epic validation · Beads

Flag Type Default Description
--json bool emit the raw verdict JSON; actions still apply
--project string project id (default: the project containing the current directory)
--round int validation round override (0 = auto-detect from prior verdict files)

koryph gc

apply data lifecycle policy: compress old run dirs, rotate audit logs

See also: Gc

Flag Type Default Description
--dry-run bool report without making any changes
--json bool emit the result as JSON
--project string apply run-dirs gc for this project

koryph inject

add a bead to a running loop even if it is outside the run's scope

See also: Running waves

Flag Type Default Description
--project string project id (default: the project containing the current directory)

koryph loop

run the binary-native autonomous supervisor

See also: Running waves · Rolling dispatch

Flag Type Default Description
--allow-api-spend bool permit api-key billing at governor stop
--auto-merge bool true allow auto-merge for merge:auto items
--budget float64 per-engine-run cost ceiling in USD (0 = unlimited)
--canary-cohort string fixed comma-separated canary bead IDs (starts at width 2)
--default-model string model for label-less beads
--direct bool owner override: merge directly instead of opening PRs
--dispatch-mode string engine dispatch mode: wave|rolling
--idle-max duration 1m0s maximum model-free idle observation backoff
--idle-min duration 1s minimum model-free idle observation backoff
--max int target project width (canary starts at exactly 2 and widens after five good outcomes)
--no-billing-guard bool make quota throttling advisory (usage is still measured)
--parent string epic scope for the bd frontier
--project string project id (default: project containing the current directory)
--require-calibration bool refuse dispatch while quota governor is uncalibrated
--review bool true require the post-validation semantic review
--runtime-equivalent string force this runtime through equivalent capability tiers
--runtime-only string dispatch only beads normally routed to this runtime
--supersede-failed-canary-cohort bool explicitly archive a failed prior generation while replacing its fixed cohort
--supersede-failed-canary-policy bool explicitly archive a failed prior generation after authenticated contract or execution-policy change

koryph models

recommend (and --apply) learned model tiers from escalation history

See also: Running waves

Flag Type Default Description
--apply bool write model: + model-learned: labels onto matching ready beads
--min-evidence int escalated-then-merged beads required per (area,size) bucket (0 = default 2)
--project string project id (defaults to the project owning the current directory)

koryph obs

manage observability: status, level, enable, disable, tail, export, prune

See also: Observability

Run koryph obs <subcommand> -h for subcommand flags.

koryph obs status

print current observability configuration

See also: Observability

Flag Type Default Description
--json bool emit as JSON

koryph obs level

set the log level for a component (or default)

See also: Observability

No flags.

koryph obs enable

enable observability (set default level to info)

See also: Observability

No flags.

koryph obs disable

silence all output (set all levels to error)

See also: Observability

No flags.

koryph obs tail

tail the telemetry JSONL stream in human-readable form

See also: Observability

Flag Type Default Description
--component string filter to this component (engine|govern|sched|…)
--follow bool stream new records as they arrive (Ctrl-C to stop)
--level string minimum level to display (trace|debug|info|warn|error)
--n int 40 number of trailing records to show (0 = all)

koryph obs export

bundle one run's telemetry as redaction-verified JSONL

See also: Observability

Flag Type Default Description
--output string write to this file instead of stdout (default: stdout)
--run string run ID to export (required)

koryph obs prune

remove telemetry files older than the retention window

See also: Observability

Flag Type Default Description
--dry-run bool list files that would be removed without removing them

koryph ops

dispatch-free operator maintenance (reconcile dead runs)

See also: Running waves

Run koryph ops <subcommand> -h for subcommand flags.

koryph ops reconcile

park zombie slots of a dead run blocked, release their leases, finalize the run

See also: Running waves

Flag Type Default Description
--dry-run bool report what would change without mutating the ledger or releasing leases
--project string project id (default: the project containing the current directory)

koryph phase

request orchestrator-owned actions from the current worker phase

See also: Running waves

Run koryph phase <subcommand> -h for subcommand flags.

koryph phase request

submit a typed phase request

See also: Running waves

Run koryph phase request <subcommand> -h for subcommand flags.

koryph phase block

report a structured capability block

See also: Running waves

koryph phase complete

write the SHA-bound terminal candidate result

See also: Running waves

koryph tui

interactive terminal cockpit (threads, queue, events)

See also: Tui

Flag Type Default Description
--a bool shorthand for --all
--all bool show every registered project (aggregate cockpit)
--all-projects bool deprecated alias for --all
--project string project id (default: the project containing the current directory)
--read-only bool disable write actions (nudge, drain) — safe for shared/observer sessions

Environment

Variable Description
KORYPH_HOME central registry + governor root (default: ~/.koryph)
KORYPH_BD_BIN path to the bd (beads) binary (default: bd on PATH)
KORYPH_GH_BIN path to the gh (GitHub CLI) binary (default: gh on PATH)
KORYPH_NO_NPX set to any value to disable npx-based tool fallbacks (e.g. ccusage)