CLI reference
Every riby command, its flags, exit codes, and where credentials live.
The riby CLI does one job: manage this machine's connection to a Riby server. Three commands. Running riby with no command, --help, or -h prints usage.
riby login [--server-url <url>] [--agent-name <name>]
riby status [--server-url <url>]
riby logout [--server-url <url>]Every command accepts --server-url to target a specific server; without it, the active server is used (defaults to https://api.runitby.you).
riby login
Authenticates the machine via a device flow and registers it as an agent.
| Flag | Purpose |
|---|---|
--server-url <url> | Log in to a specific server. It becomes the active server. |
--agent-name <name> | Name this machine's agent something recognizable (100 characters max). |
riby login --agent-name my-laptopThe CLI prints an activation link and a short code:
Open https://runitby.you/activate?code=XXXXXXXX
Enter code: XXXXXXXX
Waiting for approvalOpen the link, sign in, approve the device. The CLI polls every 5 seconds (each dot is one poll) until you approve or the code expires, then registers the agent with your hostname and platform and confirms:
Logged in as my-laptop.Credentials land in ~/.riby/config.json. One login covers the machine; every riby-mcp instance on it uses the same credentials.
riby status
The health check. Run it first when anything misbehaves.
riby statusServer: reachable (https://api.runitby.you)
Agent: my-laptop
Pending requests: 0The pending count covers all instances on this machine. What failures mean:
| Output | Meaning |
|---|---|
Server is not reachable: <url> | Network problem or wrong server URL. |
Run 'riby login' first. | No credentials on this machine. |
Login expired or revoked. Run 'riby login'. | The token was revoked (for example from the dashboard) or expired. |
riby logout
Removes this machine's credentials for the server.
riby logoutPrints Logged out from <url>., or Already logged out from <url>. if there was nothing to clear. Idempotent, so scripts can run it blind.
Exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | Any error other than authentication. |
2 | Authentication needed — run riby login. |
Code 2 is deliberate: scripts and CI steps can distinguish "log in again" from "something broke" without parsing output.
Configuration
Everything lives in ~/.riby/config.json: the active server URL and credentials per server. The CLI supports multiple servers side by side — log in to each with --server-url, and the most recent login sets the active one. Treat the file as a secret; it holds the token that lets an agent page you as you.
The MCP server (riby-mcp) reads the same file and takes no flags of its own. Its only knob is the RIBY_SESSION_NAME environment variable — see the MCP tool reference.