OpenHome CLI

The OpenHome CLI lets you build and manage Abilities from your terminal — or your favorite IDE, or an AI coding agent. Scaffold a new Ability from a template, push it to your account, set its trigger words, and voice-test it against your Agent. OpenHome’s Dashboard includes a Live Editor for performing these actions in the browser — editing an Ability’s code, setting its trigger words, and testing it against your Agent. The CLI provides the same workflow outside the browser, so you can stay within your own editor and tooling. As a standard command-line tool, the CLI can also be driven by AI coding agents such as Claude Code or Codex, or used inside agentic IDEs such as Cursor and Antigravity. This makes it a fast loop for build → push → test → deploy cycles. The CLI lives inside the open-source openhome-dev/abilities repository.

Install and Set Up

Install the CLI

Install the CLI using one of the two methods below.One-line install (macOS and Linux) is the quickest way to get started. Run:

curl -fsSL https://app.openhome.com/install.sh | sh

This installs the OpenHome CLI and makes it available in your terminal.

The one-line installer is currently in beta and may not work in every environment. If it fails, install from the repo using the method below and report it on Discord.

Installing from the repo is the right choice if you are contributing to the abilities repo or working with Ability source directly. It requires Python 3.10 or newer:

git clone https://github.com/openhome-dev/abilities.git
cd abilities
python3 -m venv cli/.venv
source cli/.venv/bin/activate        # macOS / Linux
cli\.venv\Scripts\activate           # Windows
pip install -e cli
cp .env.example .env

With either method, the OpenHome CLI becomes available from your terminal.

Authenticate the CLI with your OpenHome account:

openhome login

Paste your API key when prompted. Find it in the Dashboard under Settings → API Keys → OpenHome API Key. Your credentials are saved locally, so you only log in once.

Adding a session token (JWT). openhome login prompts only for your API key, which is sufficient for everyday commands such as agents, list, call, and chat. Uploading an Ability’s code with openhome create or openhome push may additionally require a JWT — your browser session token. If an authentication error occurs while pushing an Ability, provide a JWT explicitly:

openhome login --api-key <YOUR_KEY> --jwt <YOUR_JWT>

To get your JWT, open app.openhome.com while logged in, then either:

Run this in the browser console to copy it to your clipboard:
copy(localStorage.getItem('access_token'))
Or open DevTools → Application → Local Storage, find access_token, and copy its value.

Install voice dependencies

Voice calls (openhome call) use the mpv player and PortAudio. Install them so you can talk to your Agent:

# macOS
brew install mpv portaudio
# Linux
sudo apt install mpv portaudio19-dev

The Core Loop

Building an Ability with the CLI follows a repeatable loop: scaffold it from a template, implement your logic, push your code to test it, and commit a version once it works. Each step is a single command, so you can iterate quickly without opening the Dashboard.

Create from a template

openhome create my-weather -t api-template

This scaffolds the Ability into your local user/ workspace and pushes the initial version directly to your account, where it appears in your Abilities list. You’ll be prompted for trigger words and a description (or pass them with --triggers and --description).Your user/ workspace is private to you — it’s gitignored and never committed. You don’t need to track Ability IDs yourself; the CLI remembers which account Ability each folder belongs to, so openhome push updates the right one in place instead of creating duplicates.

Write your Ability

Open user/my-weather/main.py and implement your Ability’s logic. This file is the entry point for your Ability.

Push your code

As you make changes, push your current code to your account:

openhome push user/my-weather

This updates your Ability in place with the current contents of your folder. It does not create a committed version; it updates the working code so you can test it.

Test your Ability

Talk to your Agent and trigger the Ability with one of its trigger words:

openhome call          # real voice call
openhome chat          # text chat in the terminal

Commit a version

Once the Ability behaves as intended, commit a versioned release:

openhome push user/my-weather --commit -m "v2: better forecasts"

Committing saves a numbered version of your Ability (v1 → v2 → …) that you can continue to iterate on.

Command Reference

Account

Command	What it does
`openhome login`	Verifies and saves your credentials so you only sign in once.
`openhome agents`	Lists your Agents with their IDs and names.
`openhome templates`	Lists the templates and official example Abilities you can start from.
`openhome list`	Lists your Abilities with their IDs, state, and trigger words.

Create & Update

Command	What it does
`openhome create <name> -t <template>`	Scaffolds a new Ability from a template and pushes the first version to your account.
`openhome push <folder>`	Pushes your current code, updating the Ability in place without committing a version.
`openhome push <folder> --commit -m "<msg>"`	Commits the current code as a new version (v1 → v2).

Trigger Words & State

Command	What it does
`openhome set-triggers <id> "weather, forecast"`	Replaces an Ability’s trigger words.
`openhome enable <id>`	Enables an Ability so your Agent can trigger it.
`openhome disable <id>`	Disables an Ability so no Agent can trigger it.

Voice & Chat

Command	What it does
`openhome call [agent-id]`	Real voice call (mic + speaker) to your default Agent, or a specific one by ID.
`openhome chat [agent-id]`	Interactive text chat with an Agent (needs an ID or `OPENHOME_AGENT_ID`).

Sync & Remove

Command	What it does
`openhome sync`	Downloads your account’s Abilities into `user/`, keeping your local edits.
`openhome delete <id>`	Removes an Ability from your account and locally.

Contribute

Command	What it does
`openhome push_to_community <name>`	Copies an Ability from `user/` into `community/` for a contribution PR.

Local Link

Command	What it does
`openhome local start`	Starts the Local Link bridge in the background.
`openhome local status`	Shows whether the bridge is running.
`openhome local logs`	Streams the bridge’s requests and responses live.
`openhome local stop`	Stops the background bridge.
`openhome local run`	Runs the bridge in the foreground for debugging.

Trigger words are the spoken phrases that activate your Ability. Set them when you create an Ability, or update them at any time with openhome set-triggers.

Calling & Chatting with Your Agent

The CLI provides two ways to test an Ability against your Agent without leaving the terminal: a real voice call, or a text chat.

Voice call

openhome call             # call your default Agent
openhome call 238371      # call a specific Agent by ID

openhome call opens a live voice session: it streams your microphone to the Agent and plays the Agent’s spoken reply back through your speakers. With no ID it connects to your default Agent; pass an Agent ID to call a specific one. During a call:

Speak after the greeting — talk naturally, and the Agent responds in voice.
Press SPACE to interrupt the Agent while it’s talking.
Press Ctrl-C to hang up.

The call also streams live logs in your terminal as it runs, color-coded by level. Any logging you add inside your Ability appears here in real time, making openhome call a convenient way to observe your Ability’s behavior and debug it during a conversation. Voice calls need mpv installed (see Install and Set Up).

Text chat

openhome chat 238371      # text chat with a specific Agent

openhome chat opens an interactive text session in your terminal — type a message, press Enter, and the Agent’s reply prints back. It is the same conversation as a voice call, in plain text, and requires no audio setup. Type /quit to exit. Chat requires an Agent ID, passed directly or set via the OPENHOME_AGENT_ID environment variable.

Sync Your Account

If you built Abilities in the Dashboard, or want them on a new machine, sync downloads every Ability on your account into your user/ workspace:

openhome sync             # download your account's Abilities (keeps local edits)
openhome sync --force     # overwrite local code with the account version
openhome sync --prune     # also remove local folders for Abilities deleted on your account

By default sync only adds and updates — it never deletes your local work. Use --force to pull the account’s version over your local code, and --prune to mirror deletions you made on the account.

Contributing to the Community

Once your Ability is finished, tested, and behaving as intended, you can share it with the open-source community. The push_to_community command stages it for a pull request to the openhome-dev/abilities repository:

openhome push_to_community my-weather

This takes your finished Ability from user/ and:

Copies it into the repo’s community/ folder, stripping personal and build files (your local manifest, caches, and zips) so only the source is shared.
Runs the repo’s validator to check it meets the contribution rules, and flags anything to fix before you open a PR.
Prints the git steps to create a branch, commit, and open your pull request.

Community folder names must use hyphens only — no underscores or spaces. This step is entirely separate from your account: it prepares a contribution locally and does not change anything on app.openhome.com. See Contributing for the full review and submission guide.

Local Link

openhome local runs a small bridge on your computer that stays connected to your Agent. When your Agent needs something done on your machine, it sends the request to the bridge, the bridge runs it, and the reply goes back to the Agent — so a voice Agent can reach your computer without going through the cloud sandbox. Each request is routed to whichever local handler is available:

local-link — a raw shell executor (first-class on macOS and Linux, best-effort on Windows). Always available.
hermes — used when Hermes is installed and configured.
openclaw — used when OpenClaw is installed and its gateway is running.

The bridge detects which handlers are ready and reports them to the Agent. Anything installed but not yet usable returns a short hint on how to enable it — for example, starting the OpenClaw gateway.

openhome local start        # start the bridge in the background
openhome local status       # check whether it's running
openhome local logs         # stream requests and responses live (Ctrl-C to stop)
openhome local stop         # stop it

openhome local run          # run in the foreground for debugging (Ctrl-C to quit)

start and run accept the following options:

Flag	Default	Description
`--client-id`	`laptop`	A name for this device.
`--role`	`agent`	The connection role.
`--timeout`	`30`	Per-request timeout, in seconds.

openhome local logs shows recent history and then live-tails. Pass --no-follow to print recent logs and exit, or -n / --lines <N> to change how much history it shows first. The background bridge reconnects on its own if the connection drops; openhome local run --once connects a single time without reconnecting, which is useful while debugging.

Troubleshooting

openhome call does nothing or errors on audio

Real voice calls require the mpv player. Install it with brew install mpv portaudio (macOS) or sudo apt install mpv portaudio19-dev (Linux). If you prefer not to install it, use openhome chat for a text-based conversation instead.

“Not authenticated” or credential errors

The CLI couldn’t find a valid API key. Run openhome login and paste your key, or set OPENHOME_API_KEY in your .env file. Get your key from Settings → API Keys at app.openhome.com.

My Ability was rejected on push

Uploads are validated against OpenHome’s Ability rules — for example, only approved imports are allowed. Check that your main.py follows the template structure and doesn’t use disallowed imports, then push again.

Getting Started

Best Practices

Install and Set Up

The Core Loop

Command Reference

Account

Create & Update

Trigger Words & State

Voice & Chat

Sync & Remove

Contribute

Local Link

Calling & Chatting with Your Agent

Voice call

Text chat

Sync Your Account

Contributing to the Community

Local Link

Troubleshooting

See Also

​Install and Set Up

​The Core Loop

​Command Reference

​Account

​Create & Update

​Trigger Words & State

​Voice & Chat

​Sync & Remove

​Contribute

​Local Link

​Calling & Chatting with Your Agent

​Voice call

​Text chat

​Sync Your Account

​Contributing to the Community

​Local Link

​Troubleshooting

​See Also

Install and Set Up

The Core Loop

Command Reference

Account

Create & Update

Trigger Words & State

Voice & Chat

Sync & Remove

Contribute

Local Link

Calling & Chatting with Your Agent

Voice call

Text chat

Sync Your Account

Contributing to the Community

Local Link

Troubleshooting

See Also