Kiro CLI on Server / Raspberry Pi

Headless installation via device flow

← Back to overview

For those interested only, not part of the course.

This guide is for anyone who wants to explore the Kiro CLI with a Raspberry Pi or their own server privately. You don't need this for the workshop itself. If you're curious and want to experiment at home, here is a clean step-by-step guide.

Quick guide to set up the Kiro CLI on a remote, headless system (no desktop/browser) — e.g. an EC2 instance (via SSM) or a Raspberry Pi 5 (via SSH/SSM).

The catch on headless systems: kiro-cli login wants to open a browser that isn't there. The solution is the device flow — you get a URL + a code and sign in on another device (laptop/phone).

Prerequisites

  • A Linux system you can reach (SSH or SSM Session Manager). Tested: Debian 12 (bookworm) on ARM/aarch64 (Raspberry Pi 5).
  • Access to a browser on another device (your laptop or phone) for the login.
  • Network access from the server to the Kiro/login endpoints.

Step 1 – Sign in as the right user

Install under the user you will actually work with (not as root, not as ssm-user). Replace <username> with your actual login user:

sudo su - <username>

Why it matters: Kiro "lives" with the installing user (PATH, config under ~/.kiro, login token). If you install as root/ssm-user, you won't find the CLI in your PATH as a normal user later.

Check architecture and system briefly:

uname -m            # e.g. aarch64 (ARM) or x86_64
cat /etc/os-release

Step 2 – Base tools and installation

sudo apt update && sudo apt install -y curl unzip
curl -fsSL https://cli.kiro.dev/install | bash

At the prompt "Do you want kiro to modify your shell config?" confirm with Yes (sets the PATH automatically). Then reload the shell and check the version:

exec $SHELL -l
kiro-cli version

Step 3 – Login via device flow (headless)

On a system without a browser, use the device flow:

kiro-cli login --use-device-flow

Tip: The exact flags may differ by CLI version. When in doubt run kiro-cli login --help — the CLI shows the valid options.

The CLI asks for the login method (e.g. personal account or organization with start URL/region) and then shows a code and a URL. Steps:

  1. Open the URL on your laptop or phone.
  2. Enter or confirm the code.
  3. Sign in with your account (Builder ID, organization/SSO or Google/GitHub).
  4. The terminal reports Device authorized and then Logged in successfully.

Step 4 – Test

kiro-cli version
kiro-cli chat

In kiro-cli chat ask a simple question, e.g. "What can you do?" — if an answer appears, everything is set up. Leave the chat with /quit.

Useful commands

CommandPurpose
kiro-cli versionshow installed version
kiro-cli login --use-device-flowheadless login (URL + code)
kiro-cli login --helpavailable login options for your version
kiro-cli chatstart an interactive chat session
/model (in chat)switch model
/tools (in chat)show available tools/MCP
/quit (in chat)exit chat

Common pitfalls

  • "Opening browser…" hangs: That's the non-device flow on a headless system. Cancel with Ctrl + C and use kiro-cli login --use-device-flow.
  • kiro-cli not found: Reload the shell (exec $SHELL -l) or work as the user under which it was installed.
  • Wrong user: Don't install as root/ssm-user — see Step 1.
  • Network/proxy: The server must reach cli.kiro.dev and the login endpoints.