ax context

Context commands use the active organization, or a one-off --org <ORG_ID>. They require credentials from ax auth login, and the feature must be enabled for that organization. Every command prints a table or a detail block in an interactive terminal, and the platform's JSON when stdout is piped or --json is passed, so ax context list products | jq and scripts keep reading the same JSON. Errors and exit codes are the same in both modes.

For objects, list, get, and documents, --scope org is the default and reads the selected organization's Context. --scope global reads the shared catalog. Both scopes require access to the selected organization. Shared Context is read-only through this command group: the suggestion list returns only the suggestions you submitted, and a suggestion becomes a change only after the existing review process approves it.

context objects

Discover the Context object types and the related objects each one embeds.

ax context objects [--scope <SCOPE>] [--json]

The table shows each type with its category, whether it accepts tags, its filter columns, and the related objects get embeds (EMBEDS). Below it, each type lists its link relationships: the keys context links takes as relationship, with the target type and label:

companies
  products-offered  -> products   Products offered
  products-used     -> products   Products used
  sub-companies     -> companies  Child companies

In JSON, each object type lists its category (root, subobject, document, or tag), filterColumns, sortColumns, summaryColumns, relationships (embeds, read-side names such as productVersions) and links (each {key, targetKind, label}); types that accept tags report taggable: true. Roots are companies, products, use-cases, personas, and agents. The companies root holds Company Context objects: the companies, customers, vendors, and competitors your workspace tracks, shown as Companies in the platform. Relationship tables (for example the product to persona pairing) are not object types; their rows appear only as embedded arrays on the objects they join.

context list

List Context objects of one type as flat rows. Organization reads return newest updates first; shared-catalog reads are ordered by id.

ax context list <OBJECT> [--scope <SCOPE>] [--filter <COLUMN=VALUE>] [--tags <TAG_ID,...>] [--archived <SCOPE>] [--limit <N>] [--page-token <TOKEN>] [--json]

The table shows each row's id, name-like columns, and update time; the JSON carries every column. When more rows exist, the table ends with the next_page_token and the exact command that fetches the next page.

Examples:

# Versions of one product in the shared catalog
ax context list product-versions --scope global --filter product_id=<PRODUCT_UUID>

# Continue a matching page
ax context list product-versions --scope global --filter product_id=<PRODUCT_UUID> --page-token <NEXT_PAGE_TOKEN>

# Companies carrying either of two organization tags
ax context list companies --tags <TAG_UUID>,<TAG_UUID>

# Archived products, for example to delete them permanently
ax context list products --archived only

context get

Read one Context object with its related objects embedded one level deep.

ax context get <OBJECT> <ID> [--scope <SCOPE>] [--json]

In a terminal the object prints as a detail block: its fields first, then long text and each related collection as a named section listing every item's name and id. The response is the object's row plus one key per relationship from ax context objects: an array for many-valued relationships (personas, useCases, productVersions, documents) and an object or null for a parent (product on a product version). Items reached through a relationship table carry a link object with the link id and its metadata, such as a document's frontmatter. Each array holds at most 100 items; truncatedRelationships names any that were cut. With --scope global the related objects come from the shared catalog, and archived shared roots stay readable with their revision, archived_at, and archived_by state. An archived organization root reads the same way, with archived_at and archived_by set and its archived relations left out.

context match

Find your organization's existing company, product, persona, market, or use case before you research or create one.

ax context match --type <TYPE>[,<TYPE>...] [--name <NAME>] [--website <URL>] [--alias <ALIAS>]...
ax context match --file <PATH|->

Give at least one of --name, --website, or --alias. Each candidate lists its matches, the existing object its exact identity belongs to first (the one research reuses), its duplicates, other objects with the same identity, and its look-alikes, different objects whose names only look similar. A look-alike is never a match: decide whether it is the same object before reusing it. Archived objects never match and are listed separately. A product whose website is an existing company's homepage is flagged as that company. The JSON output is the response of POST /context/match.

Examples:

# Is MongoDB already a company or a product here?
ax context match --type companies,products --name MongoDB --website mongodb.com

# A persona by name and alias
ax context match --type personas --name "Startup founder" --alias "Founder"

context copy

Copy a shared Context object and its related Context into your organization.

ax context copy <KIND> <ID> [--request-id <UUID>]

Reuse --request-id when retrying the same copy.

Global companies, products, user-flows, user-flow-steps, use-cases, personas, and agents can be copied.

The copy also carries the published tags of the root and everything copied with it. Each shared tag is matched to an organization tag you already have (first by the tag it was copied from, then by name) or created in your library with the shared name and color; the copied objects then receive the same assignments. A tag you renamed or recolored keeps your edits, and tags or assignments you added locally are never removed. If a shared tag's name would collide with a different organization tag, the copy fails as a whole with a message naming both tags; rename or delete one of them and copy again.

context tags

Create, assign, and look up tags, the reusable labels on Context objects. Organization tags and their assignments are yours to edit; the shared library is read-only here, and shared objects take tag changes as reviewed suggestions through suggest. Every subcommand prints the platform's result: targets, list, and usage as tables, the rest as detail blocks, and all of them as JSON when piped or with --json.

ax context tags <targets|list|get|create|update|delete|assign|unassign|usage|assigned|suggest> ...

--scope global reads the shared library on list, get, usage, and assigned. --kind takes an object type from targets, such as companies or products. Names are unique per organization ignoring case and surrounding spaces. --after takes the next_page_token of the previous page. --limit accepts 1 through 100 and defaults to 50.

Examples:

# Create a tag (or get the existing one) and attach it to a Company
ax context tags create "Launch ready" --color "#0ea5e9"
ax context tags assign --kind companies --target <CONTEXT_UUID> --tag <TAG_UUID>

# Rename it using the updatedAt from `ax context tags get`
ax context tags update <TAG_UUID> --name "Launched" --expected-updated-at 2026-09-23T20:00:00.000Z

# See what carries it, then delete it once you have confirmed the count
ax context tags usage <TAG_UUID>
ax context tags delete <TAG_UUID> --expected-usage 3

# See which tags one object carries
ax context tags assigned --kind companies --target <CONTEXT_UUID>

# Propose a shared tag for a shared Company; the reply carries the suggestion id
ax context tags list --scope global --search fintech
ax context tags suggest --kind companies --target <CONTEXT_UUID> --add <TAG_UUID> --reason "Acme sells payment infrastructure"

suggest accepts 1 to 40 tag ids across --add and --remove from the shared library (list --scope global), with no id in both. A generated idempotency key is printed with the result; pass it back as --idempotency-key to retry the same proposal. You can have one pending tag proposal per shared object; to change it, pass --replaces with the pending request id and its current version as --expected-version. The proposal shows up in ax context suggest with {"action":"list","requestKind":"tag_assignment"} and is withdrawn the same way as an edit.

context links

Add, list, and remove a link between two existing organization Context objects, such as a persona and a use case, or a company and a product it offers. A link never creates or deletes either object or changes any other link. The request is the same JSON the MCP context_create_link tool takes.

ax context links schema
ax context links add --file <PATH|-> [--json]
ax context links list <OBJECT> <NAME|URL|UUID> [--relationship <KEY>] [--json]
ax context links remove <LINK_ID> [--json]

The request names each end by its exact name, AX page URL, or UUID, and relationship is a key from ax context objects for the source type:

{
  "source": { "kind": "personas", "name": "Platform engineer" },
  "relationship": "use-cases",
  "target": { "kind": "use-cases", "name": "Debug flaky CI" }
}

If a name matches several objects, nothing changes and the command lists them with their ids, so you can retry with id. A link ID names the stored link, for example company-products:<UUID>, and is the same from either end.

To link an experiment, use "kind": "experiments" as the source, naming the experiment by its id (in name), exact name, or AX page URL. The relationship is the target's type: companies, products, markets, use-cases, personas, or agents. list experiments <EXPERIMENT_ID> shows every Context object linked to the experiment, and their link IDs look like experiment-products:<UUID>. Links to product versions and persona-agent configurations can be listed and removed, not added. An experiment that matches no id or name is reported with a pointer to ax experiment list.

Examples:

# Which keys can a Company use?
ax context objects

# Link a persona to a use case, by exact name
echo '{"source":{"kind":"personas","name":"Platform engineer"},"relationship":"use-cases","target":{"kind":"use-cases","name":"Debug flaky CI"}}' \
  | ax context links add --file -

# Read back a Company's links, or only one relationship
ax context links list companies Acme
ax context links list companies Acme --relationship products-offered

# Link an experiment to a product, then read back its links
echo '{"source":{"kind":"experiments","name":"<EXPERIMENT_ID>"},"relationship":"products","target":{"kind":"products","name":"Acme CLI"}}' \
  | ax context links add --file -
ax context links list experiments <EXPERIMENT_ID>

# Remove one link; both objects stay
ax context links remove company-products:<UUID>
# Removed products-offered link between companies Acme and products Acme CLI. Both objects kept.

When the platform refuses a link because of an existing link, for example an object that already holds its only allowed link of that kind, the error names both objects and the command to run next, such as ax context links list or ax context links remove <LINK_ID>. Archived objects cannot be linked or unlinked; the error names the archived object so you can restore it or pick a live one. A name that matches nothing points you to ax context list <OBJECT>.

Link a report to Context objects

A report can be the source of a link: {"kind": "reports"} plus its exact title as name, its id, or its page URL. For a report, relationship is the target's Context object type, such as personas. These links are the report's Context properties, the same ones the report editor shows and ax report get prints.

# Link a persona to a report, by exact names
echo '{"source":{"kind":"reports","name":"Q3 onboarding review"},"relationship":"personas","target":{"kind":"personas","name":"Platform engineer"}}' \
  | ax context links add --file -

# Read back the report's links
ax context links list reports "Q3 onboarding review"

# Remove one; the report and the persona both stay
ax context links remove reports:<REPORT_ID>:personas:<PERSONA_ID>

A report link ID is reports:<REPORT_ID>:<OBJECT>:<OBJECT_ID>. A linked object that was archived or deleted lists with no name and can still be removed by its link ID.

context claim

View and manage an ownership claim for shared Context.

ax context claim <status|submit|challenge|verify|withdraw> ...

Ownership attribution does not grant direct editing rights.

Status accepts companies, products, agents, personas, use-cases, and documents. Ownership-changing actions are limited to companies, products, and agents and require an organization admin.

context follow

Follow a Context object, stop following it, or read whether you follow it. Follows belong to you and persist across organization switches; the activity feed shows you the objects you follow.

ax context follow <KIND> <ID> [--scope <SCOPE>]
ax context unfollow <KIND> <ID> [--scope <SCOPE>]
ax context follow-state <KIND> <ID> [--scope <SCOPE>]

<KIND> is companies, products, use-cases, personas, or agents. Each command reports your own follow state only: Following: yes or Following: no in a terminal, {"following": true|false} as JSON.

context documents

List the documents attached to one Context object, with each attachment's link metadata and the complete document record. Documents attach to companies, products, use-cases, personas, agents, persona-agents, interfaces, capabilities, user-flows, markets, product-packages, product-versions, product-competitors, agent-versions, and models; other object types are rejected.

ax context documents <KIND> <ID> [--scope <SCOPE>] [--limit <N>] [--page-token <TOKEN>] [--json]

A missing host returns not found; a host with no attachments returns an empty page. Continuation tokens are bound to the scope they came from, so a --scope global token cannot continue an organization listing.

context edit

Submit a JSON request that edits organization-owned Context.

ax context edit --file <PATH|->

The JSON envelope has action and input fields. Read the object before an update so the request includes its current version, and use preview-delete before a delete.

Actions are read, options, preview-delete, mutate, mutate-many, flow-steps, and document upload actions. models, agent-versions, user-flow-steps, and user-flow-step-capabilities are read-only through this editor.

Deleting a root (companies, products, use-cases, personas, agents) archives it: preview-delete answers archives: true with no effects, and the object then leaves every list and picker while it stays readable with ax context get (its row carries archived_at and archived_by) and its content, links, and experiment associations are kept. Owned records and links are still removed.

An org admin can delete an archived root permanently: on an archived root, preview-delete answers archives: false with the records that go with it (delete-owned) and any that block it (restrict), and mutate with operation: delete and that deletionToken removes the root and its owned records. Delete or detach restricting records first, such as a product's interfaces or user flows; they can be removed individually while their root is archived. flow-steps on a flow of an archived product only removes steps: send the steps to keep exactly as read (same order, text, interface and capabilities), or an empty list; additions and edits are refused.

context suggest

Submit a JSON request that reads a shared Context snapshot, creates a proposed edit or a proposed tag change, lists your suggestions, or withdraws one.

ax context suggest --file <PATH|->

Use one of these action shapes:

{"action":"snapshot","kind":"product","targetId":"<CONTEXT_ID>"}
{"action":"submit","kind":"products","targetId":"<CONTEXT_ID>","baseRevision":"1","baseline":{ "...": "snapshot response" },"proposal":{"fields":{"description":"Updated description"}},"reason":"Correct the catalog entry","evidence":[],"idempotencyKey":"<UUID>"}
{"action":"tags","op":"snapshot","kind":"companies","targetId":"<CONTEXT_ID>"}
{"action":"tags","op":"submit","kind":"companies","targetId":"<CONTEXT_ID>","add":["<TAG_ID>"],"remove":[],"reason":"Acme sells payment infrastructure","idempotencyKey":"<UUID>"}
{"action":"list","pendingOnly":true,"requestKind":"tag_assignment"}
{"action":"withdraw","id":"<SUGGESTION_ID>","version":"1"}

tags proposes changes to a shared object's shared tags for any object type from ax context tags targets. op: "snapshot" returns the object's published tags and the shared library (add search to narrow it); op: "submit" takes 1 to 40 tag ids across add and remove. list returns edit and tag suggestions together unless requestKind is suggestion or tag_assignment. ax context tags suggest builds the tags submit shape from flags.

submit requires an idempotency key. Reuse it only to retry the same submission. A replacement also needs both replacesRequestId and expectedVersion. If a submission conflicts with a newer shared Context revision, get a new snapshot, revise the proposal, then submit again.

The feature must be enabled for your organization. The command cannot approve, deny, or directly change shared Context.