ax context
Read Context objects, edit and tag organization Context, and submit reviewed edits to shared Context.
| Command | Use |
|---|---|
context objects | Discover the Context object types you can list and get. |
context list | List Context objects of one type in either scope. |
context get | Read one Context object with its related objects. |
context copy | Copy a shared object into your organization. |
context tags | Create, assign, and look up reusable tags on Context objects. |
context claim | Manage ownership claims. |
context follow | Follow, unfollow, or read your follow state for a shared object. |
context documents | List attached documents. |
context edit | Edit organization-owned Context. |
context suggest | Propose a reviewed edit to shared 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 its relationship keys. In JSON, each object type lists its
category (root, subobject, document, or tag), filterColumns,
sortColumns, summaryColumns, and relationships; 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,...>] [--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.
| Argument / flag | What it does |
|---|---|
<OBJECT> | Required. A Context object type from ax context objects, such as products or product-versions. |
--scope <SCOPE> | org (default) or global. |
--filter <COLUMN=VALUE> | Exact match on one of the object type's filterColumns, such as product_id=<PRODUCT_ID>. Repeat to AND filters. For the root types (companies, products, use-cases, personas, agents), import=<SESSION_ID> lists only the rows one Context Agent session saved; it stands alone, pages 50 rows at a time, and ignores --limit. |
--tags <TAG_ID,...> | Only objects carrying any of these comma-separated tag UUIDs (up to 20, from the same scope). Combines with --filter. |
--limit <N> | Rows per page, from 1 through 100. Defaults to 50. |
--page-token <TOKEN> | Continuation token from a prior list response using the same scope, organization, object type, and filters. |
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>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 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.
Only global companies, products, 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> ...| Subcommand | What it does |
|---|---|
targets | List the object types that accept tags. |
list [--scope <SCOPE>] [--search <TEXT>] [--after <CURSOR>] [--limit <N>] [--include-usage] | List tags in name order. --search matches names case-insensitively; --include-usage adds how many objects carry each tag. |
get <ID> [--scope <SCOPE>] [--include-usage] | Read one tag. |
create <NAME> [--color <COLOR>] | Create an organization tag, or return the existing tag with that name (created: false). |
update <ID> --expected-updated-at <TIMESTAMP> [--name <NAME>] [--color <COLOR> | --clear-color] | Rename or recolor a tag. Pass the tag's current updatedAt; the update is rejected if the tag changed. |
delete <ID> [--expected-usage <COUNT>] | Delete a tag and all of its assignments. Once a tag is in use, confirm the count from usage. |
assign --kind <OBJECT> --target <OBJECT_ID> --tag <TAG_ID> | Attach a tag to one object. Repeating it is harmless. |
unassign --kind <OBJECT> --target <OBJECT_ID> --tag <TAG_ID> | Detach a tag. Repeating it is harmless. |
usage <TAG_ID> [--scope <SCOPE>] [--kind <OBJECT>] [--after <CURSOR>] [--limit <N>] | List the objects carrying a tag. Each item names the object's parent (parentKind, parentId) when it is nested under one, such as an interface under its product. |
assigned --kind <OBJECT> --target <OBJECT_ID> [--scope <SCOPE>] | List the tags one object carries. |
suggest --kind <OBJECT> --target <OBJECT_ID> --reason <TEXT> [--add <TAG_ID>]... [--remove <TAG_ID>]... [--idempotency-key <UUID>] [--replaces <REQUEST_ID> --expected-version <VERSION>] | Propose shared-tag changes for a shared object. Staff review the proposal and publish the result; see context 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 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.
| Flag | What it does |
|---|---|
--scope <SCOPE> | global (default): a shared catalog object, which you follow by opting in. org: an object your organization owns. Every member follows the organization's objects by default, so unfollow opts you out of that object's activity and follow opts you back in. |
--org <ORG_ID> | Use this org's API key without changing the active CLI org. With --scope org it is the organization that owns the object. |
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,
product-categories, 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]| Argument / flag | What it does |
|---|---|
<KIND> | Required. One of the attachment host types listed above. |
<ID> | Required. Host object UUID. |
--scope <SCOPE> | org (default) or global. |
--limit <N> | Attachments per page, from 1 through 100. Defaults to 50. |
--page-token <TOKEN> | Continuation token from a prior context documents response using the same scope, host type, and id. |
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.
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":"product","targetId":"<CONTEXT_ID>","baseRevision":"1","proposed":{"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.