CLI command reference
The catalex command does in a terminal what the CatalEx app does on screen, and a few things the app does not offer. This page lists the commands of CatalEx 0.1.12 by task. Each row gives the command with its arguments, what it does and the page that walks through the task. For the exact flags of one command, run catalex COMMAND --help.
Install the command first: see Install CatalEx. To use the app instead, see the CatalEx app.
Options every command accepts
| Option | Meaning |
|---|---|
--json | Print one structured result with ok, command, state, data and, on failure, error.code and error.message. Branch on error.code, not on message text. |
--connection NAME | Use a saved connection (name or ID) for this one command. See CatalEx Cloud and account. |
--computer NAME | Run an agents or chats command on another computer of your account, by name or ID. |
--confirm-signing | Confirm signing a sensitive change on another computer without asking. |
With one CatalEx running on this computer, commands use it. Tuning variables for the command itself are in client environment settings.
Which commands need a sign-in
Commands that read or change your account, agents, chats, channels, computers or settings need you to be signed in, or this computer to be joined to your account. Without either, they stop with the error ACCOUNT_SIGNIN_REQUIRED (exit status 4) and tell you to run catalex login. Adding a number or workspace (catalex accounts add, catalex channels add, catalex destinations setup) needs your own sign-in even on a joined computer.
These commands run signed out, and everything else needs a sign-in:
login,join,logoutandaccount statusaccount delete, which only resumes a deletion that was already startedsetup,install,update,uninstallandpathprepare,status,start,stop,restartanddoctorproviders discover,providers connect,providers disconnectandproviders loginversion,helpandcompletion
In the tables below, the last column says No for these and Yes for the rest.
Sign in and your account
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex login | Sign in to your CatalEx account with Google in your browser. --code signs in with a one-time code from another device, --force replaces a saved sign-in, --service URL picks the service. | No | Sign in |
catalex logout | Sign out on this computer. CatalEx keeps running; --stop-agents also makes this computer leave the account. | No | CatalEx Cloud and account |
catalex account status | Show whether you are signed in. | No | CatalEx Cloud and account |
catalex account token | Print a short-lived access token for your account. | Yes | CatalEx Cloud and account |
catalex account move --to URL | Move your account to another messaging service. | Yes | CatalEx Cloud and account |
catalex account delete | Delete your account and its chat history. --impact only shows what would be erased. | No | CatalEx Cloud and account |
catalex login-codes create | Create a one-time code that signs in another device as you. | Yes | Devices |
Computers and devices
A computer runs your agents. A device is anything signed in to your account.
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex computers list | List your account's computers with their activity and last connection. | Yes | Devices |
catalex computers add | Create a one-time code that joins another computer to your account. | Yes | Devices |
catalex join | Join this computer to your account with a one-time code. | No | Devices |
catalex computers this | Show this computer's key and the device keys it trusts. | Yes | Devices |
catalex computers rename ID NAME | Rename a computer. | Yes | Devices |
catalex computers leave | Stop serving agents from this computer; your sign-in stays. | Yes | Devices |
catalex computers disconnect ID | Disconnect a computer from the account; it stops its agents at once. | Yes | Devices |
catalex computers keep ID | Keep a stale computer so it can connect again. | Yes | Devices |
catalex computers delete ID | Delete a disconnected computer and erase its agents and data. | Yes | Devices |
catalex computers settings [remote-chat-links on|off] | Show this computer's settings, or decide whether your other devices may open its chats. | Yes | Devices |
catalex devices list | List the devices signed in to your account. | Yes | Devices |
catalex devices trust ID | Trust another device for changes on your computers. | Yes | Devices |
catalex devices trust-new | Trust the devices that signed in with your sign-in codes. | Yes | Devices |
catalex devices trust-this | Trust this device through the CatalEx running on this computer. | Yes | Devices |
catalex devices remove ID | Sign another device out of your account. | Yes | Devices |
Agents
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex agents list | List saved agents, then your account's agents on other computers. | Yes | Add an agent |
catalex agents discover | List folders where Claude Code or Codex ran lately. | Yes | Add an agent |
catalex agents add | Add an agent with its folder and AI settings. | Yes | Add an agent |
catalex agents onboard | Check an existing agent folder, repair it for CatalEx and register it. | Yes | Add an agent |
catalex agents edit ID | Rename an agent or change its AI, model and effort. | Yes | AI providers, models and effort |
catalex agents delete AGENT_ID | Delete a saved agent and everything CatalEx keeps for it. | Yes | Add an agent |
catalex agents picture set AGENT_ID FILE | Set an agent's picture. picture show and picture remove read and clear it. | Yes | Add an agent |
catalex agents tools | Inspect, discover or save an agent's tools and permissions. | Yes | Tools and permissions |
catalex agents behavior | Show or change saved engagement and writing preferences. | Yes | Engagement and writing |
catalex agents limits show|set AGENT_ID | Show or change an agent's rate limits across all its accounts. | Yes | Access, approvals and limits |
catalex agents activity AGENT_ID | List settings changes made to an agent. | Yes | Activity, history and usage |
catalex agents sync | Show whether earlier conversations are synced to the server. | Yes | CatalEx Cloud and account |
catalex projects list|add|edit | Manage the folders native chats work in. | Yes | Folders, instructions and tools |
catalex delegations list|send|status AGENT_ID | Send a message to another agent on an agent's behalf, and read what it sent. | Yes | Messages between agents |
catalex messages send | Send a message to one of an agent's people now. | Yes | Messages the agent starts |
catalex messages status SEND_ID | Show the outcome of a message an agent sent. | Yes | Messages the agent starts |
Sharing an agent by link is a channel: catalex channels add --agent AGENT_ID --type share_link creates the link and prints its address. See Share an agent.
Marketplace
Every marketplace command needs a sign-in. CatalEx does not verify the repositories the Marketplace lists; check the code on GitHub before importing.
| Command | What it does | Learn more |
|---|---|---|
catalex marketplace list | List the Marketplace's agents and whether this computer has them. | Marketplace |
catalex marketplace import LISTING | Import a Marketplace agent onto the selected computer. | Marketplace |
catalex marketplace update LISTING | Update an imported agent to the offered commit. | Marketplace |
catalex marketplace add GITHUB_URL | Add a public GitHub repository to the Marketplace, then import it. | Setup file |
catalex marketplace issues LISTING | Show the setup file issues CatalEx found in your repository. | Setup file |
catalex marketplace remove LISTING | Remove one of your repositories from the Marketplace. | Marketplace |
Channels and messaging apps
A channel connects an agent to a place people write to it. These commands need a sign-in.
| Command | What it does | Learn more |
|---|---|---|
catalex channels list | List channels with their readiness. | Messaging channels |
catalex channels add | Add a native chat, Slack, WhatsApp, Google Chat, WhatsApp Personal (experimental) or share-link channel to an agent. | Messaging channels |
catalex channels remove ID | Remove a channel. Its conversations are kept, except on a linked phone number. | Messaging channels |
catalex channels behavior | Show or change a channel's engagement frequency. | Engagement and writing |
catalex accounts list | List accounts with their kind, state, agent and rules. | Messaging channels |
catalex accounts add | Add a messaging app agent or admin account. | Messaging channels |
catalex accounts remove ID | Remove a saved account. | Messaging channels |
catalex accounts health [ACCOUNT_ID] | Show each account's health and how to fix it. | Troubleshooting |
catalex accounts clear-setups | Remove every account whose setup was started and not finished. | Troubleshooting |
catalex destinations setup ACCOUNT_ID | Set up or resume a messaging app's first installation for an account. | Connect Slack, Connect WhatsApp, Connect Google Chat |
catalex credentials status|set|check|bind|unbind|installations|operation ACCOUNT_ID | Enter, replace, check or remove a messaging account's credentials. | Connect channels with an AI agent |
catalex accounts admins list|add|remove ACCOUNT_ID | Show or change who may use an admin account. | Administrator messaging |
catalex accounts access show|set ACCOUNT_ID | Show or change who may message an account (allowlist or blocklist). | Access, approvals and limits |
catalex accounts limits show|set|throttled ACCOUNT_ID | Show or change an account's rate limits, and list throttled messages. | Access, approvals and limits |
catalex channel-settings show|set|discard ACCOUNT_ID | Show or change who may act and what an account's conversations post. | Access, approvals and limits |
catalex accounts entries show|add|move|remove ACCOUNT_ID | Show or change the entries (numbers and groups) each agent answers on a shared account, such as a linked number several agents share. | WhatsApp Personal |
catalex accounts candidates ACCOUNT_ID | List the people and groups that can reach an account. | WhatsApp Personal |
catalex accounts agents engagement|settings|switches|remove | Show or set one agent's engagement depth, own settings, chat commands and system messages on a shared account, or remove it. | Engagement and writing, Access, approvals and limits |
catalex accounts manager recreate ACCOUNT_ID | Create a number's CatalEx Manager group again. | WhatsApp Personal |
catalex accounts remove-link ACCOUNT_ID | Remove a shared number that no agent uses. | WhatsApp Personal |
catalex accounts routes show|remove | List or remove the channels of agents whose computer is offline or removed. | Messaging channels |
catalex accounts template show|set|clear ACCOUNT_ID | Show or change the template an account uses to start conversations. | Messages the agent starts |
catalex accounts chats list|show|requests|answer|approve|delete | List an account's chats, read one, and answer or approve what its agent is waiting on. | Files, charts and decisions |
Native chats
Native chats are the conversations you have with an agent in the app or from the terminal. These commands need a sign-in.
| Command | What it does | Learn more |
|---|---|---|
catalex chats list | List native chats with their live activity. | Native chats |
catalex chats create | Create a native chat in an agent's native chat channel. | Native chats |
catalex chats send ID | Send a message to a native chat. | Native chats |
catalex chats show ID | Show a chat's state, settings and session. | Native chats |
catalex chats history ID | Read bounded pages of a chat's history. | Native chats |
catalex chats watch ID | Stream a chat's events for a bounded time. | Native chats |
catalex chats activity [ID] | Read a chat's full activity: tool calls, thoughts and results. | Native chats |
catalex chats cancel ID | Stop the chat's current turn. | Native chats |
catalex chats answer ID | Answer an agent's question or AI provider form. | Files, charts and decisions |
catalex chats approve ID | Grant or deny an AI provider permission request. | Files, charts and decisions |
catalex chats react ID | Add, replace or remove your reaction to a message. | Native chats |
catalex chats attachments upload|download|show|revoke | Upload, download, inspect or revoke a chat's files; show includes the transcript of a voice message or video. | Files, charts and decisions |
catalex chats import | Import a known Codex or Claude Code session as a native chat. | Native chats |
catalex chats resume ID | Resume a chat's original AI session. | Native chats |
catalex chats replace ID | Start a new AI session for a chat whose session failed. | Native chats |
catalex chats retry ID | Retry creating a chat that failed to start. | Native chats |
catalex chats remove ID | Remove a saved chat. Its saved history is kept. | Native chats |
catalex chats archive list|restore | List archived chats, or restore the ones missing on this computer. | Native chats |
catalex chats settings show ID | Show the model settings a chat started with. | Native chats |
catalex chats usage ID | Show a chat's turns, tokens, cache use and cost. | Activity, history and usage |
Activity, usage and history
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex analytics | Show every conversation and its distribution. | Yes | Activity, history and usage |
catalex analytics summary | Show message activity and cost: totals, each day, and who and where. | Yes | Activity, history and usage |
catalex usage | Show CPU, memory, disk and token usage per chat and service. | Yes | Activity, history and usage |
catalex transcript SESSION_ID | Show a Slack or WhatsApp conversation's read-only snapshot. | Yes | Activity, history and usage |
catalex hosting agents | List the agents your messaging service holds, with channel and session counts. | Yes | Activity, history and usage |
catalex hosting sessions SERVICE_ID PROJECT_ID AGENT_ID | List one agent's Slack and WhatsApp conversations on the messaging service. | Yes | Activity, history and usage |
AI providers and settings
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex providers | Show every AI provider, its version, state and whether it is connected. | Yes | AI providers, models and effort |
catalex providers discover | Detect every AI provider again and list it. | No | AI providers, models and effort |
catalex providers login PROVIDER | Sign in to Codex or Claude Code with its own sign-in on this computer. | No | AI providers, models and effort |
catalex providers connect PROVIDER | Use an installed, signed-in provider (codex or claude) in this setup. | No | AI providers, models and effort |
catalex providers disconnect PROVIDER | Stop using a provider in this setup. | No | AI providers, models and effort |
catalex refresh | Re-verify installed agents and their model inventory. | Yes | AI providers, models and effort |
catalex defaults show|set | Show or set the AI settings new agents start with. | Yes | AI providers, models and effort |
catalex connections list|add|edit|remove|use|rescan | Manage saved connections to computers and messaging services. | Yes | CatalEx Cloud and account |
catalex connections hosting show|on|off|set | Show or change the selected computer's cloud hosting. | Yes | CatalEx Cloud and account |
catalex local-setup on|off | Turn the complete setup on this computer (agents, native chats and a messaging service) on or off. | Yes | CatalEx Cloud and account |
catalex settings | Show the Developer settings catalog with defaults and ranges. | Yes | Runtime settings catalog |
catalex settings set KEY=VALUE... | Change settings; null restores a default. | Yes | Runtime settings catalog |
catalex settings advanced | Show the Advanced settings in people's units. | Yes | Capacity, storage and network |
catalex settings advanced set KEY=VALUE... | Change Advanced settings; unnamed values are kept. | Yes | Capacity, storage and network |
catalex settings endpoints show|set|operation|recover | Inspect or safely move this computer's control listener. | Yes | Capacity, storage and network |
catalex settings endpoints deployments show|set|operation|recover | Inspect or move one deployment listener. | Yes | Capacity, storage and network |
Service lifecycle, install and update
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex setup | Set up CatalEx: CatalEx Cloud, everything on this computer, or a CatalEx service URL. | No | Install CatalEx |
catalex install [COMPONENT...] | Install CatalEx from a verified release. | No | Install CatalEx |
catalex update [COMPONENT...] | Update installed components to the newest release. --check only reports. | No | Updates and everyday operation |
catalex install status | Show the installed components, their release and integrity. | No | Updates and everyday operation |
catalex uninstall [COMPONENT...] | Remove installed components; saved data is kept unless --purge is given. | No | Updates and everyday operation |
catalex path add|remove|status | Put the commands' folder on your login shell's PATH, take it off, or check it. | No | Troubleshooting |
catalex prepare | Make sure CatalEx's management service is ready on this computer. | No | Updates and everyday operation |
catalex start | Start CatalEx on the selected computer. | No | Updates and everyday operation |
catalex stop | Stop CatalEx on the selected computer. | No | Updates and everyday operation |
catalex restart | Restart CatalEx on the selected computer. | No | Updates and everyday operation |
catalex status | Show CatalEx's setup, operation and component states. | No | Updates and everyday operation |
catalex status metrics | Show how many calls CatalEx makes and receives. | No | Runtime settings catalog |
catalex doctor | Check that CatalEx is ready; exits 1 when a part is not ready. | No | Troubleshooting |
catalex version | Show the installed client version. | No | Updates and everyday operation |
The CatalEx app
| Command | What it does | Sign-in | Learn more |
|---|---|---|---|
catalex open | Launch or focus the app. --section shows agents, settings, settings/providers or settings/channels; --conversation REF opens a conversation. | Yes | The CatalEx app |
catalex app open | The same as catalex open, under app. | Yes | The CatalEx app |
catalex app status | Show whether the app runs, its version and whether it opens at login. | Yes | The CatalEx app |
catalex app quit | Quit the app; agents and chats keep running. | Yes | The CatalEx app |
catalex app login on|off | Turn opening the app when you log in to this computer on or off. | Yes | The CatalEx app |
Troubleshooting
catalex debug agents, debug projects, debug sessions list|inspect|events and debug operations inspect print what CatalEx holds, one page at a time, to help find a problem. They need a sign-in. Start with Troubleshooting and catalex doctor.