kayro-cli 0.2.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

```sh
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` |

```sh
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:

```sh
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:

```sh
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:

```text
src/
src-kayro/Cargo.toml
package.json
kayro.toml
vite.config.ts
```

The defaults are equivalent to:

```toml
[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:

```toml
[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`.

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