# q5m CLI

[q5m.ai](https://q5m.ai) brings agentic workflows to everyday life: a network
of AI agents with memory, skills, and tools to take action across the services
you already use.

Direct q5m agent-network access for Pi, OMP, scripts, and terminal users. The package talks to the q5m API over its native HTTP tool gateway and does not start MCP.

## Install

Node.js 22.19 or newer is required for the executable and Pi package. Setup can
be driven from an existing Pi or OMP session. Paste this request into the chat:

```text
Install and manage q5m for my shell and this Pi or OMP installation. The npm
package is @q5m-ai/cli. Install the CLI and the extension for this runtime. When
installation is complete, reload extensions and sign me into q5m through the
browser device flow.
```

The equivalent install commands are:

```bash
npm install --global @q5m-ai/cli
pi install npm:@q5m-ai/cli
omp install npm:@q5m-ai/cli
```

After installation, use `/q5m login` in either interactive TUI or ask the AI to
sign you into q5m. Pi and OMP expose the approval-gated `q5m_login` extension
tool for that explicit request.

q5m displays a short code and opens
[Production q5m](https://platform.q5m.ai/auth/device) in your browser. Confirm
that the browser and client show the same code, then approve the connection. The
browser session stays in the browser; the extension receives a dedicated
`q5m_...` API key only after approval. Login always connects to the production
q5m backend.

The installed executable is exactly `q5m`:

```bash
q5m --version
```

You can run the relevant install commands directly. Terminal users use the same
browser device flow:

```bash
q5m auth login
q5m auth status
q5m auth logout
```

Saved credentials live in `~/.config/q5m/config.json` with mode `0600`; the
containing directory uses mode `0700`.

Environment variables take precedence over saved configuration:

- `Q5M_API_KEY`: q5m API key
- `Q5M_API_URL`: API origin, default `https://api.q5m.ai`
  (`Q5M_ALLOW_DEVELOPMENT_LOGIN=1` is also required to log in there)
- `Q5M_GROUP_ID`: default Home, or `personal`
- `Q5M_CONFIG_HOME`: alternate configuration directory

Production remains the login default. For an explicit development-stack test,
set both variables for the login process:

```bash
Q5M_API_URL=https://platform.q5m.io/api \
Q5M_ALLOW_DEVELOPMENT_LOGIN=1 \
q5m auth login
```

Use the same environment when launching Pi or OMP if the extension should log
in to development. An unguarded `Q5M_API_URL` remains rejected during login.

## Pi and OMP

The same npm package is the `q5m` CLI plus native Pi and OMP extensions. On
startup, the extension loads Q's instructions and complete tool catalog directly
from q5m. Q's catalog tools appear as normal AI tools. Calling `list_tools` for
a peer also registers that peer's exact schemas as active tools named:

```text
q5m_<agent>__<tool>
```

For example, a `create_event` tool on the `google-calendar` peer becomes `q5m_google-calendar__create_event`. Read-only q5m tools may run in parallel. Destructive tools require interactive confirmation; Pi and OMP reject them in non-interactive modes.

Use `/q5m` or `/q5m status` to inspect connection status, `/q5m login` to
authenticate through your browser, `/q5m reload` after an external configuration
change, and `/q5m logout` to revoke and remove the saved credential. The
approval-gated `q5m_login` tool provides the same flow after an explicit
natural-language request. Either runtime can also load the extension for one run:

```bash
pi -e npm:@q5m-ai/cli
omp -e npm:@q5m-ai/cli
```

## Human commands

```bash
q5m agents
q5m agent q --json              # Q's host instructions and tool catalog
q5m agent google-calendar
q5m route "schedule a cycling workout"
q5m tools google-calendar
q5m tool google-calendar create_event \
  --input '{"title":"Ride","start":"2026-08-24T08:00:00-07:00"}'
q5m recall "the restaurant we discussed" --limit 5
```

Inspect Q's complete catalog:

```bash
q5m catalog
q5m tools
```

Call any catalog tool by name:

```bash
q5m call get_memory --input '{"path":"/profile"}'
q5m call save_memory --input-file request.json
cat request.json | q5m call save_memory --input-file -
```

Interactive terminals receive concise human-readable output. Redirected output is JSON automatically; `--json` or `-j` forces JSON explicitly:

```bash
q5m agents --json | jq '.[] | .slug'
```

Errors use stable JSON and process exit codes:

```json
{"error":{"code":"not_installed","message":"Agent is not installed","status":403}}
```

- `0`: success
- `1`: request, network, or server failure
- `2`: command usage or input error
- `3`: authentication or authorization failure

## Homes

The default Home controls Q's memory, skills, and other Home-scoped tools:

```bash
q5m context
q5m context personal
q5m context <group-id>
```

Use `--group personal|GROUP_ID` to override Q's Home for one command. Peer dispatch normally resolves the Home where that peer is installed. If a peer exists in multiple Homes, use `--home personal|GROUP_ID` with `q5m tool`:

```bash
q5m tool carpool list_rides --home <group-id> --input '{}'
```

The backend verifies group membership. A stale or spoofed group selector falls back to Personal and cannot widen access.