CLI reference
Every median command, its arguments and flags, and the role it needs.
median <group> <command> [args] [flags]Install and sign in with the CLI guide. Endpoints behind each command are in the management API reference.
Conventions
| Item | Meaning |
|---|---|
--json |
Every command. Prints one JSON value on stdout |
--help, --version |
Help for any command, and the installed version |
--no-<flag> |
Sets a boolean flag to false, for example --no-enabled |
| Repeatable | The flag can be passed more than once |
<ms> |
A Unix timestamp in milliseconds |
<id> |
For a conversation, customer, document or signal argument, a median.sh link to it works too. Not in --conversation flags |
| Role Any | A signed in account. No organization needed |
| Role Member | Anyone in the organization |
| Role Admin | Admins and owners. See roles |
Aliases
| Group | Alias |
|---|---|
read |
open |
orgs |
org |
conversations |
convos, inbox |
knowledge |
kb |
signals |
signal |
tasks |
task |
integrations |
int |
Session
| Command | Args and flags | Role |
|---|---|---|
login |
--api <url> sets the API address. Default https://api.median.sh, or MEDIAN_API_URL |
Any |
logout |
Revokes this machine’s session | Any |
whoami |
Account, bound organization and role | Any |
read
| Command | Args and flags | Role |
|---|---|---|
read <link> |
A /signal/, /inbox/, /customers/ or /knowledge/ link. Anything else fails with not_a_link |
Member |
orgs
| Command | Args and flags | Role |
|---|---|---|
orgs list |
The bound one is marked * |
Any |
orgs current |
Member | |
orgs create <name> |
--slug. Without it the slug is the name in lowercase, so a name with spaces or punctuation fails with invalid_slug. Pass --slug for those. Binds this session and your dashboard to the new organization |
Any |
orgs rename |
--name, --slug. Pass at least one |
Admin |
orgs use <org> |
An id or slug. Rebinds this session only | Any |
A slug is 3 to 32 lowercase letters, numbers and single dashes. Reserved words such as admin, api, app, help, median, support and team are refused. You can be in 50 organizations at most.
keys
| Command | Args and flags | Role |
|---|---|---|
keys list |
Masked values only | Admin |
keys create |
--name. Prints MEDIAN_KEY and the publishable key once |
Admin |
keys revoke <id> |
Admin |
conversations
| Command | Args and flags | Role |
|---|---|---|
conversations list |
--status, one of open, resolved, closed. --channel, one of widget, email, discord. --archived. --waiting for threads that need a person. --limit up to 200, default 50 |
Member |
conversations get <id> |
Every message, notes included | Member |
conversations reply <id> |
--body, required. Takes the thread off the AI |
Member |
conversations note <id> |
--body, required. Team only |
Member |
conversations resolve <id> |
Member | |
conversations close <id> |
Member | |
conversations reopen <id> |
Member | |
conversations archive <id> |
Member | |
conversations unarchive <id> |
Member | |
conversations read <id> |
Member | |
conversations unread <id> |
Member | |
conversations snooze <id> |
--until, required. 30m, 2h, 3d, 1w or <ms> |
Member |
conversations wake <id> |
Cancels a snooze | Member |
conversations pause <id> |
Takes the thread off the AI | Member |
conversations resume <id> |
Hands it back to the AI | Member |
conversations delete <id> |
Archived conversations only | Member |
customers
| Command | Args and flags | Role |
|---|---|---|
customers list |
--limit up to 100, default 50 |
Member |
customers get <id> |
Profile, learned facts, conversations | Member |
customers refresh <id> |
--rebuild wipes the learned profile and rereads every conversation |
Member |
customers reach-out <id> |
--body or --file <path>, one required. --subject, email only. --agent sends as the AI agent, which answers the reply. --brief tells the agent what to achieve |
Member |
customers forget <id> <factId> |
Removes one learned fact | Member |
customers delete <id> |
Deletes the customer and every conversation they had | Member |
knowledge
| Command | Args and flags | Role |
|---|---|---|
knowledge list |
Folders and documents | Member |
knowledge search <query> |
--source, one of upload, manual, github, notion, web, learned. Matches titles |
Member |
knowledge get <id> |
Member | |
knowledge write |
--title, required. --body or --file <path>, one required. --folder <id> |
Admin |
knowledge edit <id> |
--title, required. --body or --file <path>, one required. Synced documents refuse |
Admin |
knowledge delete <id> |
Admin | |
knowledge move <id> |
--folder <id>, top level if left out. --order, default 0 |
Admin |
knowledge retry <id> |
Indexes a failed document again | Admin |
knowledge sync |
Resyncs every connected repository and Notion page | Admin |
knowledge folders create <name> |
--description, --parent <id>. Three levels deep at most |
Admin |
knowledge folders rename <id> |
--name, required. --description. Leaving it out keeps the current one |
Admin |
knowledge folders move <id> |
--parent <id>, top level if left out. --order, default 0 |
Admin |
knowledge folders delete <id> |
Its contents move up a level | Admin |
knowledge suggestions list |
Admin | |
knowledge suggestions approve <id> |
Writes it into the library | Admin |
knowledge suggestions dismiss <id> |
Admin | |
knowledge crawls list |
Admin | |
knowledge crawls start <url> |
The same site again updates pages already imported | Admin |
knowledge crawls remove <id> |
Cancels a running crawl | Admin |
signals
Statuses: open, planned, "in progress", "in review", done, declined. Quote the two with spaces. Priorities: urgent, high, medium, low.
| Command | Args and flags | Role |
|---|---|---|
signals list |
--kind, bug or suggestion, required. --filter, one of live, all or a status. The default live hides done and declined |
Member |
signals get <id> |
Reporters and claimed commits | Member |
signals file |
--kind, --title, --priority, required. --body. A repeated title fails with signal_exists |
Member |
signals edit <id> |
--title, required. --body. Leaving it out keeps the description |
Member |
signals status <id> <status> |
done messages every reporter |
Member |
signals priority <id> <priority> |
Member | |
signals accept <id> |
Sends it to every connected tracker and plans it | Member |
signals merge <id> |
--duplicate <id>, required. The duplicate folds into <id> |
Member |
signals delete <id> |
Nobody is told | Member |
signals commits apply <id> |
Accepts the commit as the fix and closes the signal | Member |
signals commits dismiss <id> |
Member |
tasks
Statuses: requests, planned, in_progress, in_review, done. <task> is a key like MED-12, a number or an id. See Tasks.
| Command | Args and flags | Role |
|---|---|---|
tasks list |
--status. --assignee as an email or user id. --limit up to 100, default 100 |
Member |
tasks get <task> |
With every commit and pull request on it | Member |
tasks create |
--title, required. --description or --file <path>. --status, default planned. --priority, one of urgent, high, medium, low. --assignee |
Member |
tasks edit <task> |
--title, --description, --file <path> |
Member |
tasks status <task> <status> |
--place, top or bottom, default bottom |
Member |
tasks priority <task> <priority> |
A priority, or none to clear it |
Member |
tasks assign <task> <person> |
Email or user id | Member |
tasks unassign <task> |
Member | |
tasks delete <task> |
Tracker issues stay | Member |
tasks requests |
--limit up to 60, default 60 |
Member |
tasks adopt <signal> |
--status, default planned |
Member |
tasks decline <task> |
Cards in requests only |
Member |
tasks settings |
With no flags, prints the settings. --prefix, --code on or off, --issues <owner/repo> or off, --watch <owner/repo> and --unwatch <owner/repo> change them |
Member reads, Admin changes |
feedback
| Command | Args and flags | Role |
|---|---|---|
feedback submit |
--from, required. A stable id for the person, 8 to 128 characters. --body or --file <path>, one required. --page <url>, --name, --email. --image <url>, repeatable. The last 6 are kept |
Member |
With --json, outcome is bug, suggestion, spam or unread. unread means nothing was filed, because the reader was unavailable or filing is off. Without --json it prints one sentence, like Filed as a bug (<id>).
tools
| Command | Args and flags | Role |
|---|---|---|
tools list |
Each endpoint with its tools, risk and switch | Member |
tools enable <name> |
Admin | |
tools disable <name> |
Admin | |
tools endpoint add <url> |
Connects a route, or resyncs one already connected. A Median key must exist | Admin |
tools endpoint remove <id> |
Its tools go with it | Admin |
tools endpoint sync |
--url <url> when more than one endpoint is connected |
Admin |
tools approvals |
--conversation <id> for one thread’s recent calls |
Member |
tools approve <id> |
The call runs now | Member |
tools deny <id> |
Member | |
tools status <id> |
One call’s state and result | Member |
tools run <conversation> <tool> |
--input <json>. Runs now as the team, with no approval |
Member |
tools test <tool> |
--input <json> with flat string, number and boolean values. --as <user id>. --conversation <id> uses its stored visitor and cannot be combined with --as. Runs at any risk with no approval. Exits 1 when the tool fails |
Admin |
tools suggestions list |
--prompt <id> prints one brief in full |
Admin |
tools suggestions built <id> |
Admin | |
tools suggestions dismiss <id> |
Admin |
agent
| Command | Args and flags | Role |
|---|---|---|
agent get |
Admin | |
agent set |
--name, 2 to 40 characters. --personality, up to 2,000. --on <switch> and --off <switch>, both repeatable |
Admin |
| Switch | Dashboard label |
|---|---|
requireEmail |
Ask for an email |
messagePreview |
Preview replies |
autoResolve |
Resolve conversations automatically |
learnFromThreads |
Learn from resolved conversations |
suggestKnowledge |
Suggest knowledge and tools |
nightlySweep |
Review the inbox nightly |
fileSignals |
Track bugs and suggestions |
integrations
Connect each integration in the dashboard first. Channels, roles and teams go in by name. Repositories are written owner/repo.
| Command | Args and flags | Role |
|---|---|---|
integrations status |
Member | |
integrations email |
--enabled or --no-enabled. The first time on issues your address |
Admin |
integrations slack |
--channel <name>, --enabled |
Admin |
integrations discord |
--tickets <channel>, --staff <role>, --no-ping to ping nobody, --mirror <channel>, --mirroring, --enabled |
Admin |
integrations linear |
--team <key or name>, --auto opens an issue as each signal is filed |
Admin |
integrations issues set <repo> |
--auto |
Admin |
integrations issues off |
Open issues stay open | Admin |
integrations commits watch <repo> |
--branch, --close closes the signal when the fix merges |
Admin |
integrations commits stop <repo> |
Admin | |
integrations repos connect <repo> |
--branch, --path <folder>, --published-at <url> |
Admin |
integrations repos published <repo> <url> |
Admin | |
integrations repos remove <repo> |
Imported documents stay | Admin |
site
The public site’s look, domain and sign-in. See Site themes, Custom domain and Site sign-in.
| Command | Args and flags | Role |
|---|---|---|
site get |
Member | |
site set |
--theme paper, --scheme system, light or dark, --navigation top, sidebar or topics, --accent <hex> or --accent theme for the theme’s own |
Admin |
site css pull [file] |
Prints the CSS without a file | Member |
site css push <file> |
Replaces the whole stylesheet, up to 60,000 characters | Admin |
site css clear |
Admin | |
site domain get |
Prints the DNS records still to add | Member |
site domain set <hostname> |
Replaces any other domain. Prints the DNS records to add | Admin |
site domain check |
Checks the DNS records now | Member |
site domain remove |
Back to <slug>.median.website |
Admin |
site sign-in get |
The method, its settings and the OIDC redirect URI | Member |
site sign-in set <method> |
median, app or oidc. --app-url <url> for app. --issuer, --client-id and --client-secret for oidc; leave out the secret to keep the saved one |
Admin |
members and invites
| Command | Args and flags | Role |
|---|---|---|
members |
Lists everyone with their user id | Member |
members role <userId> <role> |
owner, admin or member |
Admin |
members remove <userId> |
What they wrote stays. Your own id leaves the organization, which any member may do | Admin, or anyone for themselves |
invites list |
Admin | |
invites create <email> |
--role, one of member, admin, owner. Default member. Also prints the invitation’s path |
Admin |
invites revoke <id> |
Admin |
Only an owner can make or invite an owner. Admins cannot change or remove other admins or owners. Nobody can change their own role, and the last owner cannot be demoted or removed.
webhooks
Events: message.created, conversation.created, conversation.updated, bug.created, suggestion.created, signal.updated, knowledge.suggestion.created.
| Command | Args and flags | Role |
|---|---|---|
webhooks list |
Admin | |
webhooks add <url> |
--event, repeatable. Default every event. A Median key must exist |
Admin |
webhooks update <id> |
--url <url>. --event, repeatable. Replaces the list |
Admin |
webhooks remove <id> |
Pending retries stop too | Admin |
analytics
| Command | Args and flags | Role |
|---|---|---|
analytics overview |
Member | |
analytics conversations |
--days, one of 7, 30, 90. Default 30. --from <ms> |
Member |
analytics satisfaction |
Same as conversations | Member |
analytics signals |
Same as conversations | Member |
analytics knowledge |
Same as conversations | Member |
analytics billing |
Same as conversations. Amounts in microcredits | Member |
analytics activity |
Same as conversations | Admin |
analytics fields <dataset> |
A dataset’s field ids, kinds, values and time fields | Member |
analytics explore |
--query <json>, required. --days, 1 to 366. Default 30. --from <ms> |
Member, Admin for the logs dataset |
analytics records |
Same as explore, measure optional. --limit up to 200, default 50 |
Member, Admin for the logs dataset |
Every command here except overview, fields and records prints JSON with or without --json.
billing
| Command | Args and flags | Role |
|---|---|---|
billing overview |
Plan, credits left, add-ons, this period’s use | Admin |
billing invoices |
--cursor. --limit up to 100, default 25 |
Admin |
billing limits |
Your API rate limit tier. Prints JSON | Member |
billing usage |
--from <ms> and --to <ms>, default the last 30 days. --cursor. --limit up to 100, default 100. Prints JSON |
Member |
logs
| Command | Args and flags | Role |
|---|---|---|
logs list |
--from <ms> and --to <ms>, default the last 30 days. --snapshot <ms>, --cursor. --limit up to 200, default 100. --search. --category. --outcome. --by. --actor <userId>. --conversation <id>. --usage for billed usage only |
Admin |
logs get <id> |
The entry, plus up to 50 entries about the same conversation | Admin |
| Flag | Values |
|---|---|
--category |
ai, tools, knowledge, conversations, customers, signals, integrations, webhooks, email, team, keys, access, settings, billing, api, system |
--outcome |
success, failed, denied, pending, canceled |
--by |
member, agent, assistant, customer, api, system |
A page that is not the last ends with more: --cursor <cursor> --snapshot <ms>. Pass both to read the next page.
docs
| Command | Args and flags | Role |
|---|---|---|
docs search <query> |
--limit up to 8, default 5 |
Member |
docs read <route> |
A route such as /agent/tools, or the page’s address. Prints the page as markdown |
Member |
call
| Command | Args and flags | Role |
|---|---|---|
call |
Lists every method | Member |
call <method> |
A method of the MCP client, such as conversations.reply. --data <json> for its arguments. Always prints JSON |
The method’s |
median call conversations.list --data '{"needsHuman":true}'
median call signals.setPriority --data '{"signalId":"q57...","priority":"high"}'Method names, arguments and answers match median.<method> in median_run. A method added to Median works here without updating the CLI.
api
| Command | Args and flags | Role |
|---|---|---|
api <method> <path> |
<method> is GET, POST, PATCH, PUT or DELETE. --data <json> for the request body. Always prints JSON |
The endpoint’s |
median api GET /v1/me
median api PATCH /v1/tasks/MED-12 --data '{"status":"done"}'median api sends your session token, so it cannot call the messaging routes (/v1/config, /v1/thread, /v1/messages, /v1/typing, /v1/uploads). Those take MEDIAN_KEY and answer invalid_api_key to anything else.