MCP reference

orion mcp start serves these tools over stdio. Each one runs a CLI command, so it reads and writes the same data.

orion_card_list

List work items with their derived status

Runs orion card list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
group	id	Only items inside this group
all	boolean	Include done items

orion_card_create

Add a work item

Runs orion card create.

Argument	Type	Description
label	string	Required. What the work is
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
group	id	Group to add it to
after	id	Item the card follows; it lands beside it, in its group
before	id	Item the card leads into; it lands beside it, in its group
status	todo | active | review | blocked | deferred | done	todo, active, review, blocked, deferred, or done
repo	string	Repository it belongs to, as owner/name (empty to clear)
who	you | review | ci	Whose move: you, review, or ci (empty to clear)
note	string	Free-form note. Write it as a plain-language summary: Markdown for structure, code formatting for code, file paths, and identifiers, and no pull request or issue links in the text. Attach those as refs on a card.
shape	service | store | actor | external | interface | process | queue	How a component is drawn: service, store, actor, external, interface, process, or queue (empty to clear)
color	teal | blue | purple | amber | rose | green | slate	A component's tint: teal, blue, purple, amber, rose, green, or slate (empty to clear)
kind	step | gate | component	step; gate for one that's done once everything it waits on is; or component for a part of a system, not work. A note given a kind becomes a work item
ref	string	Attach outside work: a GitHub or Jira URL, source:key such as jira:ABC-1, or branch:owner/name@branch

orion_card_set

Change an item's fields

Runs orion card set.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
label	string	New label
status	todo | active | review | blocked | deferred | done	todo, active, review, blocked, deferred, or done
repo	string	Repository it belongs to, as owner/name (empty to clear)
who	you | review | ci | ""	Whose move: you, review, or ci (empty to clear)
note	string	Replaces the whole note, and empty clears it. Write it as a plain-language summary: Markdown for structure, code formatting for code, file paths, and identifiers, and no pull request or issue links in the text. Attach those as refs on a card.
shape	service | store | actor | external | interface | process | queue | ""	How a component is drawn: service, store, actor, external, interface, process, or queue (empty to clear)
color	teal | blue | purple | amber | rose | green | slate | ""	A component's tint: teal, blue, purple, amber, rose, green, or slate (empty to clear)
kind	step | gate | component	step; gate for one that's done once everything it waits on is; or component for a part of a system, not work. A note given a kind becomes a work item
ref	string	Attach outside work: a GitHub or Jira URL, source:key such as jira:ABC-1, or branch:owner/name@branch

orion_card_timeline

Show a card's timeline: its most recent log entries, newest first

Runs orion card timeline.

Argument	Type	Description
id	id	Required. Card id
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
limit	integer	How many recent entries to show (default 5)

orion_card_done

Mark one or more items done

Runs orion card done.

Argument	Type	Description
ids	string list	Item ids or selectors
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select targets with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_card_chain-close

Close out a done card and every waiting done card chained to it through finished cards, the same as double-clicking a shimmering card in the app. Closing out a chain is the person's reward for finishing it, so don't close out on your own: finishing a card with orion_card_done leaves it waiting for them. Close out only when the person asks.

Runs orion card chain-close.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
dryRun	boolean	Preview the chain and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_card_import

Add a card for each URL or source:key in one step

Runs orion card import.

Argument	Type	Description
refs	string list	Required. GitHub or Jira URLs, or source:key such as jira:ABC-1
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
group	id	Group to add the cards to
dryRun	boolean	Preview the cards without writing
ifRevision	integer	Write only if the document has this revision

orion_card_snooze

Hide items from attention and orion next until a time

Runs orion card snooze.

Argument	Type	Description
ids	string list	Item ids
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
until	string	Required. When it wakes: an ISO 8601 date or date-time, in local time unless it ends in Z or an offset
where	string	Select items with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_card_unsnooze

Show snoozed items again right away

Runs orion card unsnooze.

Argument	Type	Description
ids	string list	Item ids
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select items with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_note_create

Add a note, optionally between two linked items

Runs orion note create.

Argument	Type	Description
text	string	Required. Note text. Write it as a plain-language summary: Markdown for structure, code formatting for code, file paths, and identifiers, and no pull request or issue links in the text. Attach those as refs on a card.
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
group	id	Group to add it to
after	id	Item the note follows
before	id	Item the note leads into

orion_link_create

Link each adjacent pair of items

Runs orion link create.

Argument	Type	Description
from	id	Required. The item that has to happen first
to	id	Required. The item that waits on it
next	string list	Further items in the chain
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
related	boolean	Link without blocking
label	string	What the link carries, such as HTTP (empty to clear)
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_link_remove

Remove the link between two items

Runs orion link remove.

Argument	Type	Description
from	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
to	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_link_insert

Insert an item into an existing link, replacing it with two links of the same kind

Runs orion link insert.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
target	string list	Target item whose link is replaced
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
between	id	Required. Source item whose link is replaced (required)
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_node_show

Show one item or group

Runs orion node show.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_node_query

Find cards and groups with an expression. Fields: kind, repo, status, recordedStatus, group, draft, label, pr, ref, note, snoozed. Compare quoted values with = or !=, quoting numbers and booleans too; label, ref, and note also take ~ for case-insensitive text.

Runs orion node query.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Required. Expression selecting cards or groups (required)
all	boolean	Include done items

orion_node_find

Find cards and groups whose label, note, or refs contain text

Runs orion node find.

Argument	Type	Description
text	string	Required. Text to find, matched case-insensitively
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
limit	integer	Most matches to print (default 20)
allCanvases	boolean	Search every canvas, not only this one

orion_node_remove

Remove items. Removing a note reconnects the links that ran through it

Runs orion node remove.

Argument	Type	Description
ids	string list	Item ids or selectors
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select targets with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision
reconnect	boolean	Also reconnect cards with at most one incoming and one outgoing link; every selected card must qualify

orion_node_move

Move items or groups into another group

Runs orion node move.

Argument	Type	Description
ids	string list	Item or group ids or selectors
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select targets with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision
to	id	Destination group
top	boolean	Move to the top level

orion_group_list

List groups with their progress

Runs orion group list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_group_create

Make a group: empty, optionally inside another, or wrapping items that share a parent

Runs orion group create.

Argument	Type	Description
label	string	Required. Group name
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
items	string list	Comma-separated ids to wrap; the group goes where they are
in	id	Group to make an empty group inside

orion_group_remove

Remove groups with everything inside them

Runs orion group remove.

Argument	Type	Description
ids	string list	Group ids or selectors
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select targets with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_group_set

Change a group's fields

Runs orion group set.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
label	string	New label
blurb	string	Group description
arrange	auto | custom	How reflow arranges a group: auto (default) flows by dependency, custom keeps items where they are
cover	string	Image asset id for the cover, from orion media add --json (empty to clear)
background	string	Color, color token such as card.background, or image asset id (empty to clear)
header	string	Markdown with layout HTML shown under the group's title (empty to clear)
color	teal | blue | purple | amber | rose | green | slate | ""	The group's tint: teal, blue, purple, amber, rose, green, or slate (empty to clear)

orion_group_ungroup

Dissolve groups, keeping their items in place

Runs orion group ungroup.

Argument	Type	Description
ids	string list	Group ids or selectors
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select targets with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_group_tidy

Mark groups for the app to lay out in place, deepest first, such as after adding cards in bulk. The app does the layout, so appConnected in the result says whether it runs now or when the app next opens. Custom groups keep their arrangement.

Runs orion group tidy.

Argument	Type	Description
ids	string list	Group ids
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
where	string	Select groups with an expression instead of ids
dryRun	boolean	Preview changes and current revision without writing
ifRevision	integer	Write only if the document has this revision

orion_ref_remove

Take a ref off an item

Runs orion ref remove.

Argument	Type	Description
id	id	Required. Item or group id, or a selector such as label:"Extract slider", ref:jira:ABC-12, or pr:86
ref	string	Required. The ref's key as orion node show lists it, such as owner/name#12, or a URL or source:key
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_next

List items that can start now, most unblocking first

Runs orion next.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_apply

Apply a plan of cards, notes, groups, and links in one call. The plan is a list of operations that run in order, and it lands whole or not at all. addCard and addNote create items, and group wraps items; each may declare a handle, and later operations refer to it as "@handle". Existing cards and groups are named by id. Other operations: setFields, link, unlink, insert, move, ungroup, tidy, remove, removeGroup. Use dryRun to preview the plan and the ids each handle gets.

Runs orion apply.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
plan	object list	Required. Operations in order. Each has an op field, such as addCard with label, or link with from and to. New cards and notes are placed after the last operation, beside the items they link to. Move needs group, or null for the top level.
dryRun	boolean	Preview the plan without writing
ifRevision	integer	Write only if the document has this revision

orion_canvas_list

List canvases and mark the active one

Runs orion canvas list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
archived	boolean	List archived canvases instead

orion_canvas_create

Create a canvas with its own data folder

Runs orion canvas create.

Argument	Type	Description
name	canvas	Canvas name. Omit it to derive one from --label
label	string	Display label

orion_canvas_rename

Change a canvas's display label

Runs orion canvas rename.

Argument	Type	Description
name	canvas	Required. Canvas name
label	string	Required. New display label

orion_canvas_set

Set a canvas's cover or background

Runs orion canvas set.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
cover	string	Image asset id for the cover, from orion media add --json (empty to clear)
background	string	Color, color token such as card.background, or image asset id (empty to clear)
header	string	Markdown with layout HTML shown over the top of the canvas (empty to clear)

orion_canvas_archive

Archive a canvas. Its data stays in place, and restore brings it back. The active canvas and default can't be archived

Runs orion canvas archive.

Argument	Type	Description
name	canvas	Required. Canvas name

orion_canvas_restore

Restore an archived canvas with its data

Runs orion canvas restore.

Argument	Type	Description
name	canvas	Required. Archived canvas name

orion_canvas_use

Make a canvas the active one

Runs orion canvas use.

Argument	Type	Description
name	canvas	Required. Canvas name

orion_canvas_check

Report layout problems from stored positions and sizes: overlapping siblings, children outside their group, links to missing items, and groups waiting for layout. Returns a list of {kind, ids, bounds} in canvas coordinates, with bounds null for a dangling link, and an empty list when the layout is clean.

Runs orion canvas check.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
group	id	Only problems in this group or inside it

orion_log_add

Log what happened, optionally attached to cards. Corrections are new entries.

Runs orion log add.

Argument	Type	Description
text	string	Required. What happened
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
card	string list	Card ids to attach the entry to, comma-separated
agent	string	Required. The agent's name, such as claude.

orion_log_list

List the canvas log, newest first

Runs orion log list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
card	id	Only entries attached to this card
limit	integer	Show at most this many of the newest entries

orion_server_status

Report the running Orion server

Runs orion server status.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_source_list

List configured sources

Runs orion source list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_source_add_github

Add a GitHub source

Runs orion source add github.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
host	string	Required. GitHub host
owners	string list	Required. GitHub owners, comma-separated
include	string list	Repositories to include, comma-separated
exclude	string list	Repositories to exclude, comma-separated
id	string	Source id

orion_source_add_hop

Add a hop source

Runs orion source add hop.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
id	string	Source id

orion_source_remove

Remove an ingestion source

Runs orion source remove.

Argument	Type	Description
id	string	Required. Source id
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_source_matches

List unplaced pull requests and the cards they likely belong to

Runs orion source matches.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_ingest

Import work from configured sources and refresh the cards they track

Runs orion ingest.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
dryRun	boolean	Show changes without writing
source	string	Only ingest this source id

orion_media_add

Insert a media node from a file

Runs orion media add.

Argument	Type	Description
file	string	Required. Absolute path to a local PNG, JPEG, GIF, or WebP file, which is copied into the canvas.
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
label	string	Node label
group	id	Group to put the node in

orion_media_list

List media nodes

Runs orion media list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_suggestion_find

Compute group suggestions

Runs orion suggestion find.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
scope	unsorted | all	unsorted or all
dryRun	boolean	Show suggestions without writing

orion_suggestion_list

List the stored group suggestions

Runs orion suggestion list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_suggestion_apply

Apply group suggestions

Runs orion suggestion apply.

Argument	Type	Description
ids	string list	Suggestion ids
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
all	boolean	Apply every suggestion

orion_suggestion_dismiss

Dismiss group suggestions

Runs orion suggestion dismiss.

Argument	Type	Description
ids	string list	Suggestion ids
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
all	boolean	Dismiss every suggestion

orion_ci_list

List the CI jobs snoozed on the canvas

Runs orion ci list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_ci_snooze

Leave a CI job's failures off every card in a repository until it passes, or until a time

Runs orion ci snooze.

Argument	Type	Description
name	string	Required. The job's name, as GitHub shows it
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
repo	string	Required. Repository the job runs in, as owner/name (required)
until	string	End the snooze at a UTC time such as 2026-10-14T18:00:00Z, or a date. Without it, the snooze lasts on each card until the job passes there

orion_ci_unsnooze

Count a snoozed CI job's failures on cards again

Runs orion ci unsnooze.

Argument	Type	Description
name	string	Required. The job's name, as GitHub shows it
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
repo	string	Required. Repository the job runs in, as owner/name (required)

orion_theme_add

Copy a theme file into the data folder, where the app lists it

Runs orion theme add.

Argument	Type	Description
file	string	Required. Absolute path to a local .json theme file with light and dark token values.
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_theme_list

List the theme files in the data folder

Runs orion theme list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_theme_remove

Delete a theme file from the data folder

Runs orion theme remove.

Argument	Type	Description
file	string	Required. Theme file name, as theme list shows it
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_backup_list

List saved Orion data revisions

Runs orion backup list.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_backup_restore

Restore a saved revision as a new revision

Runs orion backup restore.

Argument	Type	Description
revision	string	Required. Revision to restore
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_focus

Show the group open in the app and what's selected

Runs orion focus.

Argument	Type	Description
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.

orion_reveal

Select cards or groups in the open Orion app and zoom the canvas to them, opening the group they share. Opens the app when it's closed. Set selectOnly to select without moving the camera.

Runs orion reveal.

Argument	Type	Description
ids	string list	Required. Item or group ids to reveal
canvas	canvas	Canvas name. Omit to use the canvas selected in Orion.
selectOnly	boolean	Select them without moving the camera