Skip to main content
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

1

Clone the abilities repo

git clone https://github.com/openhome-dev/abilities.git
cd abilities
2

Install the CLI

Run from the repo root. Requires Python 3.10 or newer.
python3 -m venv cli/.venv && source cli/.venv/bin/activate
pip install -e cli
Once installed, the openhome command is accessible from any directory.
3

Set up your environment file

Create your .env from the provided example:
cp .env.example .env
4

Log in

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

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

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

Write your Ability

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

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

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
5

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

CommandWhat it does
openhome loginVerifies and saves your credentials so you only sign in once.
openhome agentsLists your Agents with their IDs and names.
openhome templatesLists the templates and official example Abilities you can start from.
openhome listLists your Abilities with their IDs, state, and trigger words.

​
Create & Update

CommandWhat 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

CommandWhat 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

CommandWhat 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

CommandWhat it does
openhome syncDownloads your account’s Abilities into user/, keeping your local edits.
openhome delete <id>Removes an Ability from your account and locally.

​
Contribute

CommandWhat it does
openhome push_to_community <name>Copies an Ability from user/ into community/ for a contribution PR.
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:
  1. 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.
  2. Runs the repo’s validator to check it meets the contribution rules, and flags anything to fix before you open a PR.
  3. 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.

​
Troubleshooting

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

​
See Also