Matrix from the terminal

Install

The installer is a short shell script. It checks for Python, downloads the one file the command is, verifies it against the checksum published beside it, and puts it in ~/.local/bin/matrix. Nothing runs as root and nothing else on the machine is touched.

curl -fsSL https://matrix.pratimana.com/install.sh | bash

If ~/.local/bin is not on your PATH the installer says so and prints the line to add to your shell profile. To install somewhere else, set MATRIX_INSTALL_DIR first:

MATRIX_INSTALL_DIR=/usr/local/bin bash -c "$(curl -fsSL https://matrix.pratimana.com/install.sh)"

Prefer to read it first? The script is at /install.sh and the command itself at /cli/matrix.py, with its checksum at /cli/matrix.sha256. Downloading that file and marking it executable is the whole install.

Requirements

• macOS, Linux, or Windows through WSL.
• Python 3.8 or newer, as python3 or python. Nothing else is installed: the command uses only the standard library.
• curl, for the installer and for matrix update.

Sign in

A terminal cannot follow the magic link the sign-in page sends, so the command signs in through your browser instead, the way gh auth login does.

matrix login

Sign in to Matrix

  Open   https://matrix.pratimana.com/cli-auth?code=BCDF-GHJK
  Code   BCDF-GHJK

Approve this terminal in the browser. Waiting… (Ctrl-C to stop)

Signed in as you@example.com (Security Researcher).

On a desktop the link opens on its own. Sign in there if you are not already, check the code on the page matches the one in the terminal, and click Approve. The terminal notices within a few seconds. A code lasts fifteen minutes and approves exactly one terminal; to sign in on another machine, run matrix login there.

The credential the terminal receives is the one the web app holds: a fifteen-minute access token, renewed on its own from a refresh token that rotates on every use and lasts a week of inactivity. It is kept in ~/.config/matrix/credentials.json, readable only by you.

Commands for everyone

Programs and their scope are public, so these work before you sign in; signed in, they also show the private programs you were invited to.

matrix program abc-logistics

abc Logistics
=============
Slug        abc-logistics
Type        public
Status      active
Bounties    $100–$5000
Response    72 h

In scope
KIND    TARGET                 NOTE
------  ---------------------  --------------------------
domain  api.abclogistics.com   Production API
domain  app.abclogistics.com   Customer portal

Scope rules
KIND          APPLIES TO             WEAKNESSES                    NOTE
------------  ---------------------  ----------------------------  -------------------
out_of_scope  app.abclogistics.com   Clickjacking on a page with…  Known, on the roadmap

Researchers

Filing from the terminal is for the report you wrote in your editor: the body is Markdown, from a file or standard input, and the rest is flags. The program's safe-harbor terms still have to be accepted, once, with --accept-safe-harbor.

Submitting a report

matrix report submit \
  --program abc-logistics \
  --title "IDOR: any order readable by id on /api/orders" \
  --asset api.abclogistics.com \
  --type "Insecure direct object reference" \
  --cvss "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N" \
  --weakness broken_access_control.idor \
  --file report.md --steps-file steps.md \
  --accept-safe-harbor

The answer names the report and prints any scope rule that matched: a target the program has declared out of scope, a weakness it does not pay for. Attachments are not supported from the terminal yet; add them to the report on the site.

Organizations

The same command signed in as an organization member sees the organization's side: its programs, the queue, and triage. What each member may do follows their role on the site.

matrix queue --assigned me

ID        TITLE                                         PROGRAM         SEVERITY  STATUS    BOUNTY  SUBMITTED
--------  --------------------------------------------  --------------  --------  --------  ------  ----------------
c5dd12a6  Stored XSS in shipment tracking widget        abc Logistics   high      triaging          2026-09-09 18:02
9b1e04f7  SSRF via webhook configuration on partner o…  abc Logistics   critical  new               2026-09-09 17:58

matrix triage c5dd12a6 --status triaged --bounty 750 --note "Confirmed on staging; fix scheduled."

MCP server

The same command speaks the Model Context Protocol, so an AI assistant can use Matrix as you: read a program's scope, look up the right weakness, draft and file a report, or work the triage queue. matrix mcp runs on your machine, over standard input and output, with the credentials from matrix login. There is nothing to host and no extra sign-in.

Add it to your assistant

Claude Code:

claude mcp add matrix -- matrix mcp

Claude Desktop, in claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "matrix": { "command": "matrix", "args": ["mcp"] }
  }
}

Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json, under "servers") take the same shape. If the app cannot find matrix on its own PATH, give the full path: "command": "/Users/you/.local/bin/matrix".

Tools

Every tool answers structured JSON. The four that write are marked as such in the protocol, so a well-behaved assistant asks before running them, and the server's own instructions tell it to show you the exact arguments first. The API enforces every permission exactly as it does for the site: an assistant connected as a researcher cannot triage, and one connected as an organization member cannot file reports.

Resources and prompts

Resources let an assistant attach context without a tool call: matrix://programs, matrix://programs/<slug>, matrix://reports/<id> and matrix://me. Two prompts set it up for the common jobs:

• draft_report (program, finding) puts the program's scope, rules and reward tiers in front of the assistant with what you found, and asks for a complete report — vector, weakness, steps — shown to you before anything is submitted.
• triage_queue (program, optional) lists the open reports and asks for a proposed status, bounty and note for each, against the scope and tiers, to be applied only as you confirm them.

Trying it by hand

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"0"}}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | matrix mcp

Set MATRIX_MCP_DEBUG=1 to log each method to standard error. Standard output is the protocol channel, so nothing else is ever written to it.

The API

The command line, the MCP server and the site all speak to one API at https://matrix.pratimana.com/api, with a bearer token from matrix login or the browser session. Every route, its verbs and what it answers is listed in the API reference; --json below prints exactly what those routes return.

JSON and scripting

Every command that lists or shows something takes --json and prints exactly what the API answered, so the output can go to jq or a script instead of a person.

matrix reports --open --json | jq -r '.[] | [.id[0:8], .severity, .title] | @tsv'

matrix programs --json | jq -r '.[] | select(.offers_bounties) | .slug'

Errors go to standard error and the exit code is 1; an interrupted command exits 130. A validation error from the API is printed field by field.

Reports are addressed by id. The tables print the first eight characters, and every command that takes an id accepts that prefix as long as it is unambiguous among your reports; scripts should use the full id from --json.

Configuration

Update and uninstall

matrix update

Fetches the newest copy of the command from the site, verifies it against the published checksum, and replaces the installed file in place. matrix update --check only says whether there is one. Running the installer again does the same.

rm ~/.local/bin/matrix && rm -r ~/.config/matrix

That is the whole uninstall: the command and its credentials. Run matrix logout first if you want the refresh token revoked on the server as well.

Troubleshooting

Security

• The command is a single readable Python file with no dependencies, served over HTTPS with a SHA-256 checksum beside it; the installer and matrix update refuse a download that does not match.
• Signing in never types a password into the terminal. The browser approves a short code that expires in fifteen minutes and works once; the page shows which computer asked and from where.
• The credentials file is created with mode 600. The access token in it lasts fifteen minutes; the refresh token rotates on every use and is revoked by matrix logout.
• A "view as" session in the web app cannot approve a terminal, so an administrator looking at someone's account cannot mint a credential in their name.
• Report a problem with the command itself to security@pratimana.com.