Kayro CLI
kayro is the human- and agent-friendly command line for Kayro desktop apps.
It discovers kayro.toml, generates app-local TypeScript types, runs Vite, and
builds the Rust host without requiring an npm package.
Everyday use
kayro dev generates src/kayro.gen.ts, starts the configured Vite command,
waits for its TCP endpoint, then starts the native app. Closing the app stops
Vite. Ctrl-C stops the complete Unix process group or Windows process tree,
including child processes.
kayro build generates types, builds Vite, produces a release native
executable, and packages the current OS's default distributable. Exact artifact
paths are printed to stdout. Use --debug or
--profile NAME for another Cargo profile, and --target-dir DIR to isolate
artifacts.
| OS | Zero-config output | Optional formats |
|---|---|---|
| macOS | DMG containing the app bundle | app, dmg |
| Windows | NSIS setup EXE | nsis (setup alias), msi |
| Linux | AppImage | appimage, deb |
Kayro supplies a built-in icon when the project has none and downloads/caches
required packager tooling on first use. Bundles are built only on their native
OS; use matching CI runners for releases and --no-bundle for cross-compiled
executables.
Run kayro dev --help and kayro build --help for all Cargo feature, job,
offline, frontend-only, and native-only switches.
Terminal experience
Human output uses aligned phases, compact status symbols, relative paths, and
one live native compilation line. Kayro derives the total from Cargo's
versioned metadata graph and advances it from unique compiler-artifact
messages, so the bar reflects real Rust build work rather than a timer. Cargo's
per-crate lifecycle lines are hidden by default while warnings and errors remain
visible. Pass --verbose to restore lifecycle lines and exact subprocess
commands. The progress UI works for type generation, development, and release
builds.
In an interactive terminal Kayro also emits OSC 9;4 progress sequences. Terminals
that support the convention can mirror the percentage in their tab or system
UI; other terminals safely ignore it. The sequence is cleared on success,
failure, and interruption. Use --color auto|always|never to control ANSI
colors, or set NO_COLOR. OSC progress is independent of color and is never
written in JSON mode.
New and existing projects
kayro new NAME writes the complete Vite, TypeScript, Rust, and configuration
layout, generates src-kayro/Cargo.lock, and runs bun install. It never asks
interactive questions:
After --no-install, run both setup steps yourself:
kayro init [DIR] initializes an empty directory or adds the Kayro native side
to an existing Vite app. Existing package.json, Vite config, HTML, source,
README, and ignore files are preserved byte-for-byte. Kayro reuses existing
dev:web/build:web scripts, or falls back to dev/build, and refuses any
native-file collision instead of overwriting it.
Vite itself marks #, ?, and * as unsafe in its project-root path. Kayro
rejects those paths before dependency installation or Rust compilation, with a
stable unsupported_vite_path JSON error. Move or rename the project (including
its parent directories) before running Vite.
Zero-config defaults
The CLI walks up from the current directory to find kayro.toml. A standard
Kayro layout needs no [build] table:
src/
src-kayro/Cargo.toml
package.json
kayro.toml
vite.config.ts
The defaults are equivalent to:
[]
= "."
= "src-kayro/Cargo.toml"
= ["bun", "run", "dev:web"]
= ["bun", "run", "build:web"]
= "http://127.0.0.1:5173"
[]
= true
Commands are argument vectors, not shell strings, so spaces and quoting behave
consistently across platforms. Vite receives KAYRO_DEV_URL,
KAYRO_DEV_HOST, and KAYRO_DEV_PORT during development. Paths are relative
to kayro.toml.
Bundle metadata is optional and app-local:
[]
= true
= "1.2.0" # defaults to src-kayro/Cargo.toml
= "Example Inc."
= "Example desktop app"
= "Copyright 2026 Example Inc."
= ["icons/app.png"]
= ["assets/notice.txt"]
= "13.0"
Set active = false to keep kayro build executable-only by default; an
explicit --bundles still requests packaging. macOS distribution signing is
enabled with APPLE_SIGNING_IDENTITY. Notarization uses
APPLE_KEYCHAIN_PROFILE, APPLE_ID/APPLE_PASSWORD/APPLE_TEAM_ID, or the
supported App Store Connect API-key variables. Without credentials, a local DMG
is produced but is not claimed as signed or notarized.
Agents and automation
--json guarantees newline-delimited JSON on stdout for help, errors, process
output, compile progress, lifecycle changes, and artifacts. Every record includes
schema_version, sequence, elapsed_ms, and event.
--quiet removes chatty command_output records while retaining the plan,
phase results, errors, and artifacts. Without --quiet, compilation emits
throttled compile_progress events with completed, total, percent, and
package. Packaging adds bundle_planned, bundle_started,
bundle_artifact, and bundle_finished events. --dry-run reads and validates
the project but never starts a process or writes generated files.
Stable exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Internal I/O or signal-handler failure |
| 2 | Invalid arguments, project, or configuration |
| 3 | Required tool not found |
| 4 | Build/dev process failure or readiness timeout |
| 130 | Interrupted by Ctrl-C |
--arch maps aarch64/arm64, x86_64/x64, and i686/x86 to the host
operating system. --target accepts any Rust target triple directly. Kayro
does not silently install Rust targets, SDKs, or cross-linkers; Cargo reports a
clear failure if the requested toolchain is unavailable.