CLI reference

kyra --help prints this from the command itself, and is authoritative if the two ever disagree. kyra help <command> prints one command’s full detail.

curl -fsSL https://dl.kyra-hi.com/install.sh | sh

Needs Node 22.6 or newer. See connect your computer for the full walkthrough.

Commands at a glance

Command	Does
login	Authorise this machine against your account
connect	Hold the channel open so Kyra can see and drive your sessions
install	Wire an application so Kyra can drive it
uninstall	Remove that wiring
init	Install the agent skill so a session can talk back
bridge	Run the local door in the foreground
pull	Clone or refresh a notebook to local files
push	Write local note edits back
consent	Set how much Kyra asks before changing things
update	Install the latest published build over this one
version	Print the version and build stamp
help	Help for a command

---

kyra login

Authorise this machine. Prints a short code and a link — open it, confirm the code matches, and the credential is stored under ~/.kyra/ readable only by you.

The credential grants Kyra control of coding agents on this machine. Revoke it from Settings → Coding agents in the portal; that is an instant kill-switch and does not need access to the machine.

---

kyra connect

kyra connect [options]

Leave it running while you work. The connection is outbound only — no port is opened on your machine.

It also starts the local door if none is running, so Kyra can reach applications here too.

Option	Meaning
--permission-mode <read|write|execute>	What sessions Kyra spawns may do. read (default) reads files, write also edits, execute also runs commands.
--codex	Use Codex for sessions whose spawn names no agent.
--workdir <dir>	Root sessions here instead of the current directory.
--pull	Also let Kyra refresh your local notes on command. Costs one extra read-only approval.
--watch [notebooks]	Auto-refresh notebooks when a note changes (implies --pull). Bare = every cloned notebook, or a comma-separated list.
--no-bridge	Do not start the local door. Applications on this machine stay unreachable.
-v, --verbose	Trace the channel and the agent’s own output.

Environment: KYRA_PERMISSION_MODE, KYRA_AGENT, KYRA_DEBUG=1, KYRA_API_BASE.

kyra connect
kyra connect --permission-mode write --verbose
kyra connect --workdir ~/code/my-app --watch notes,work

Important

The directory you start it in is the writable root. Sessions can read more widely but only write inside it.

Note

One daemon per directory. A second kyra connect in the same directory is refused — they would share one session store. Use another directory or --workdir.

Warning

--verbose echoes the agent’s raw output, which can include your code. Do not share that log from a session that handled secrets.

Stop with Ctrl-C. It says goodbye, revokes any note-pull key, and removes the local key before exiting.

---

kyra install and kyra uninstall

kyra install <app>...        # short: kyra -i <app>
kyra uninstall <app>...
kyra install --status        # show what is wired, change nothing

Takes applications like a package manager. Today vscode is the only one; run kyra install with no arguments to see what is available.

For VS Code it points the Claude Code extension at Kyra’s mediation shim by setting claudeCode.claudeProcessWrapper in your own settings.json. That setting belongs to the Claude Code extension, which is why it goes in your settings rather than somewhere Kyra owns. Comments and formatting are preserved, and nothing is written unless the result still parses.

Every VS Code on the machine is wired, including Insiders and the remote/WSL one.

Important

Sessions already open stay unmediated until you reopen them — the wrapper applies when a session starts. Same on the way out.

More →

---

kyra init

kyra init [--codex]

Installs the Kyra Agent Skill into the agent’s skills directory so a running session can tell Kyra two things: “I’m blocked on a question” and “I’ve finished, here’s the gist”.

Safe to re-run, and re-running is how you pick up a newer skill after a CLI upgrade.

---

kyra bridge

kyra bridge [-v] [--dir <dir>]

Runs the local door in the foreground.

You usually never type this — kyra connect starts one when none is running and stops it on a graceful exit. Run it yourself to watch frames go past while building a provider, or to hold the door open without a daemon.

It never dials the network. Without a kyra connect, it routes locally between whatever is attached and nothing reaches Kyra — which is exactly what developing and testing a provider needs.

Option	Meaning
-v, --verbose	Log every frame.
--dir <dir>	Where the socket and token live (default ~/.kyra/bridge).
--version	The bridge’s version, which is this CLI’s.

Ctrl-C removes the socket and the token — a token that outlives its process is a live key lying on disk.

Note

Only a graceful shutdown stops a door that kyra connect started. Kill it hard and the door outlives it, idle and reaching nothing, until you stop that process. The next kyra connect finds it and leaves it alone.

Not available on native Windows — why.

---

kyra pull

kyra pull --vault <slug> [--out <dir>]

Clones or refreshes a notebook into ~/.kyra/vaults/<slug>/. It mints a temporary read-only key, uses it, and discards it — there is no SSH key for you to set up.

The first run asks you to approve read-only note access in the portal.

---

kyra push

kyra push --vault <slug> [-m <message>] [--out <dir>]

Pushes the local clone back up. kyra pull must have made it first.

Needs its own approval in the portal — write is a separate, higher-trust grant than read.

A dirty tree is refused unless you pass -m, which stages and commits everything first. Otherwise commit with git yourself and kyra push only does the network write.

kyra push --vault notes -m "notes from the drive home"

Working with notebooks as Git →

---

kyra consent

kyra consent                                   # what is in force now
kyra consent posture <plan|ask|trusted>
kyra consent sensitivity <low|normal|high> [--target <id>]
kyra consent clear [--target <id>]

Sets how much Kyra asks before it changes things. Two settings that both have to agree before a question is skipped.

Reading it happens here. Changing it finishes in a browser: the last three commands print a link and a short code, you confirm there, and the command reports what is now in force.

That round-trip is deliberate, and it is not about doubting you. The credential this machine holds is the one that lets Kyra run code on this machine — so anything that credential can change by itself is something a compromise of this machine can change. Both settings apply to your whole account, so a machine that could set them could relax your real editor from a scratch container. Confirming in the browser is what keeps “I decided this” true.

Kyra itself has no tool for any of it and cannot change it, which is the same point one level up. Settings → Desktop control in the portal does the same job without the code.

The full explanation →

---

kyra update

kyra update            # install the latest published build
kyra update --check    # say what is available, install nothing

Downloads the current build, checks it against the published checksum, and installs it over this one. Nothing is installed when you are already on the latest version.

It stops rather than guessing in three cases:

• npm’s global directory needs root. It says which directory and stops; re-run it with sudo. It never escalates on its own.
• You are running kyra from a git checkout. Updating that is git’s job. Installing over it would leave you with a second copy and whichever one your PATH finds first.
• The build needs a newer Node than you have. npm would install it anyway and leave you with a kyra that cannot start, so this refuses and points you at the installer, which can upgrade Node for you.

Option	Does
--check	Report what is available and install nothing
--force	Install even when the versions match, or when the host will not say what it is serving
--allow-downgrade	Permit moving to an older build than the one installed
--allow-unverified	Install a build that publishes no checksum

--force on its own will not move you backwards — a rollback also needs --allow-downgrade. The version it judges that against comes from the downloaded build itself, not from what the host advertises, so it holds even when there is no published version to compare with.

--allow-unverified is a flag rather than an environment variable on purpose. The installer takes KYRA_CLI_ALLOW_UNVERIFIED=1 because curl … | sh has no arguments to pass it, and that value dies with the command line; an exported variable would quietly waive the checksum on every future update. It never waives a checksum that is present and wrong — that always refuses.

Note

A running kyra connect keeps serving the build it started with. Restart it after updating, and run kyra init to refresh the agent skill.

---

kyra version

Prints the semver and the git build stamp. Quote both when reporting a problem — the daemon announces them on connect, so they identify exactly which build ran. A build run from source reports dev.

---

kyra help

kyra help              # every command
kyra help connect      # one command in full
kyra connect --help    # the same

---

Files it uses

Path	What
~/.kyra/	Your credential, readable only by you
~/.kyra/bridge/	The door’s socket and its per-run token
~/.kyra/vaults/<slug>/	Notebooks fetched by kyra pull
~/.claude/skills/kyra	The agent skill (~/.codex/skills/kyra with --codex)