Command Line Usage

Run Kaya programs and manage the local daemon

Kaya's command line has two user-facing executables:

kaya starts and interacts with program sessions.
kayad explicitly controls the local daemon process.

kayad owns the native HTTP/session service and language execution. Programs outside supported native capabilities receive structured admission errors. The standalone archive also contains the required colocated kaya-tool-server; keep all three executables together. See installation and release availability.

Run a program

Pass a local .kaya file to the explicit run command:

kaya run workflow.kaya
kaya run workflow.kaya --set topic=science --set count=3

Repeat --set KEY=VALUE to supply program inputs; a value can contain additional = characters. Each value parses as JSON when valid and binds as a string otherwise, so --set count=3 binds the number 3 while --set topic=science binds a string. To force a string that would otherwise parse, pass a JSON string literal: --set k='"123"' binds "123". Use the global --session option to give the new session a stable handle:

kaya --session editorial-draft run workflow.kaya --set topic=science

Read a large input value from a file instead:

kaya run workflow.kaya --input-file task=task.json

The file content follows the same JSON-when-valid rule; a missing or unreadable file fails the launch. A key passed through both --set and --input-file is an error — pass it once.

A YAML launch profile can select the program, initial inputs, and session/cache folders. Override a nested profile value with repeatable --set options:

kaya run job.yaml --set inputs.topic=science --set folders.cache=./.cache

Job-config values retain their YAML types, and --set inputs.* overrides follow the same JSON-when-valid rule. The CLI does not infer input names from arbitrary options, read a value as a file merely because it resembles a path, or download programs from URLs.

Session commands

Command	Purpose
`kaya run <program>`	Create a session and stream it to completion
`kaya defer <program>`	Create a session without immediately running it
`kaya resume <session> [job.yaml]`	Resume, optionally using project-scoped storage
`kaya send <session> [message]`	Send text or a structured event
`kaya listen <session>`	Stream an existing session's events
`kaya session list`	List one daemon-index page
`kaya session show <session>`	Print a session record as JSON
`kaya session delete <session>`	Delete a stopped session
`kaya session delete <session> --force`	Delete a running session

Session references can be an exact ID, a handle, an unambiguous ID prefix, @ for the newest stored session, or @-N for an earlier one. send sends plain text by default. Structured events require an explicit --event-type; --data must be a JSON object. The daemon stamps event provenance.

Resuming a saved program uses its captured immutable source snapshot. Editing the original .kaya file does not change the saved program's source. Stop older daemons manually before upgrading to the native control protocol; the product version is separate from daemon protocol and HTTP binding 2.0.0.

kaya send my-session --event-type game.move --data '{"x":3,"y":7}'

Local source commands

Command	Purpose
`kaya check <path>`	Report parse and semantic diagnostics
`kaya fmt <path>`	Print canonically formatted Kaya source
`kaya fmt -w <path>`	Format Kaya files in place
`kaya fmt --check <path>`	Exit nonzero when formatting differs

These commands run in the Rust CLI process and do not contact kayad.

Local cache and session analysis

kaya cache clear clears the local cache. Use --dir DIR to select its path, --dry-run to report without removing files, and --json for a JSON report. The default path is $KAYA_CACHE_DIR or ~/.kaya/cache.

kaya cache clear --dir ./cache --dry-run --json
kaya analyze usage --all --sessions-dir ./sessions --json
kaya analyze metrics @ --sessions-dir ./sessions

kaya analyze [SESSION_REF] reports both usage and metrics. The optional usage, metrics and all subcommands select the report. References include @, @-N, an ID, a unique ID prefix or a path. Without a reference or selection filter, analysis uses the latest stored session, or an empty report if none exists.

All analysis forms accept --sessions-dir DIR (alias --sessions-root), --all, --last COUNT, --since DURATION (alias --sessions-since) and --json. Durations use whole seconds, minutes, hours or days, such as 30s, 10m, 2h or 1d. Put filters after the report subcommand when using one. The sessions root defaults to $KAYA_SESSIONS_DIR or ~/.kaya/sessions.

Both command groups operate locally without contacting kayad; they do not require the separate source-built kaya-utils executable.

MCP server profiles

kaya mcp configures the local Rust MCP gateway. The command group can add HTTP or stdio servers, log in to OAuth-capable servers, inspect discovered and allowed tools, replace allowlists, remove profiles, diagnose connectivity, and control the local supervisor. Run kaya mcp --help for the complete generated contract. Credentials and private upstream endpoints are redacted from command output.

kaya doctor reports local daemon, credential and tool readiness, with JSON output and optional rendering/agent profiles. An acp command group is not part of the Rust CLI; use the separately built native ACP adapter described below.

Use kaya --help for the top-level command list and kaya --version for the installed version.

Daemon selection and auto-start

By default, daemon-backed commands connect to http://localhost:5292 and the API prefix /kaya/. If that local daemon is absent, kaya uses kayad start and waits until the native daemon reports healthy.

Use the global --daemon-url <url> option to select another endpoint for a daemon-backed command.

kaya --daemon-url http://127.0.0.1:5300 run workflow.kaya

Auto-start is limited to plain-HTTP loopback endpoints. A remote or HTTPS URL is an explicit external service choice: it must already be running, and kaya will report a connection error instead of launching an unrelated local daemon.

Manage `kayad`

Normal local use does not require a manual daemon command. Use these lifecycle commands for development, operations, or troubleshooting:

kayad serve                    # foreground; logs stay in this terminal
kayad start                    # background; wait until healthy
kayad status                   # report Kaya ownership and daemon health
kayad stop                     # stop the Kaya-owned daemon
kayad restart                  # stop, start, and wait until healthy

Bare kayad prints help and exits with a usage error because the lifecycle must be explicit.

All lifecycle commands accept endpoint options:

Option	Default	Meaning
`--host <address>`	`127.0.0.1`	Daemon listen address
`--port <number>`	`5292`	Daemon listen port
`--path-prefix <path>`	`/kaya/`	HTTP API prefix

serve, start, and restart also accept --persist-dir and --log-level; adapter-specific options are available as well. The former worker source watcher (--dev or -d) is retired and returns a launch error. Use generated Clap help for the complete, current option set:

kayad serve --help
kayad status --help

kayad only manages processes it owns for the selected endpoint. It will not claim or terminate an unrelated service that happens to use the same port.

Other native tools

The standalone installer contains only kaya, kayad and kaya-tool-server. Use kaya check and kaya fmt for local validation and formatting.

These separate Rust tools require Kaya repository access and a source build; they are not standalone installer payloads:

kaya-check: Fast standalone parse and semantics validator.
kaya-fmt: Code formatter (shares its Rust implementation with kaya fmt).
kaya-lsp: Native Language Server Protocol daemon for editor integration.
kaya-acp: Native Agent Client Protocol (ACP) adapter harness.
kaya-utils: Secondary developer utilities for cache management (kaya-utils cache clear) and session telemetry analysis (kaya-utils session analyze).

See the native ACP guide for source-built adapter usage and editor setup for language support availability.