kayro-cli 0.1.0

Create, build, and run Kayro desktop apps for humans and agents
Documentation

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

cargo install kayro-cli

kayro new my-app
cd my-app
kayro dev
kayro build
kayro build --arch arm64
kayro build --target x86_64-apple-darwin
kayro build --no-bundle

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 build --bundles app,dmg
kayro build --bundle-dir dist/installers
kayro build --no-bundle

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:

kayro new notes --app-name "Kayro Notes" --identifier com.example.notes
kayro new notes --directory apps/desktop --no-install

After --no-install, run both setup steps yourself:

cargo generate-lockfile --manifest-path src-kayro/Cargo.toml
bun install

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:

[build]
frontend_dir = "."
native_manifest = "src-kayro/Cargo.toml"
dev_command = ["bun", "run", "dev:web"]
build_command = ["bun", "run", "build:web"]
dev_url = "http://127.0.0.1:5173"

[bundle]
active = 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:

[bundle]
active = true
version = "1.2.0" # defaults to src-kayro/Cargo.toml
publisher = "Example Inc."
description = "Example desktop app"
copyright = "Copyright 2026 Example Inc."
icons = ["icons/app.png"]
resources = ["assets/notice.txt"]
macos_minimum_system_version = "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.

kayro build --json --quiet
kayro build --json --dry-run --arch arm64

--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.