Machine surface

CLI

The same retrieval your agents run, from a terminal or a cron job. One file, no dependencies, no build step, and no package registry in the way. Read it before you run it; it is short.

Install and authenticate

# One file, served by this deployment. No registry account involved.
curl -fsSL https://www.contextely.com/cli.mjs -o contextely && chmod +x contextely
./contextely --help

# Save a key once, to ~/.config/contextely/config.json (mode 0600).
./contextely config set-key ctx_sk_...

# Or keep it in the environment instead, which is what CI wants.
export CONTEXTELY_API_KEY=ctx_sk_...

Create the key under API keys in the dashboard. It speaks as one member, so the CLI can never retrieve more than the person whose key it holds.

Commands

Every command below is the same code path as the MCP tool named beside it, so a terminal and an agent cannot end up looking at different answers.

contextely search "<question>" [--limit N] [--skip-refresh] [--subject S] [--meta k=v ...]

MCP tool: context_searchmetered: query

Search the workspace's condensed memory as the member this key belongs to.

contextely related <memory-id> [--limit N]

MCP tool: context_related

Walk from one memory object to its nearest neighbours.

contextely expand <memory-id>

MCP tool: context_expandmetered: refresh

Read the full current record from the system of record behind a memory object.

contextely get <memory-id>

MCP tool: memory_get

Print one memory object.

contextely remember "<text>" [--title T] [--scope S] [--team ID] [--visibility V] [--id K] [--review-after S] [--subject S] [--meta k=v ...]

MCP tool: memory_add

Store something worth remembering. --visibility says who it is shared with, --scope what clearance a reader needs.

contextely list [--subject S] [--limit N] [--cursor C] [--meta k=v ...]

List stored memory newest first. Without --subject, only memory that has no subject.

contextely forget-subject <subject> [--meta k=v ...]

Erase every memory of one subject (optionally only those matching --meta). Needs a memory-write key.

contextely graph "<question>" [--depth N] [--limit N]

MCP tool: graph_searchmetered: query

Search, then follow the relationships around what it found. Every triple names the memory that asserted it.

contextely neighbours <memory-id|--name NAME> [--depth N] [--limit N]

MCP tool: graph_neighbours

What one memory object or one named entity is connected to.

contextely history <memory-id>

MCP tool: memory_history

What this memory used to say, and when each version was believed.

contextely forget <memory-id> [--graph-only]

MCP tool: memory_forget

Remove a memory, or with --graph-only keep the fact and rebuild its relationships.

contextely record [--session ID] [--query "..."] [--used ID] [--client NAME]

MCP tool: session_record

Record one step of an agent run and the memory its answer used.

contextely rate <turn-id> --score N [--note "..."]

MCP tool: session_feedback

Say whether a recorded answer was any good. 1 to 5.

contextely sources

MCP tool: sources_list

List the connected systems of record.

contextely source-tools

MCP tool: source_tools_list

List the source tools you may call directly, without going via condensed memory.

contextely call <tool> [--arg k=v ...]

MCP tool: source_tool_callmetered: refresh

Call one source tool directly. The answer comes back unranked: Contextely gates the call, not the records.

contextely usage

MCP tool: workspace_usage

Show the plan and what is left of this month's allowance.

contextely ingest <source-id> [--limit N]

Sync one source: read its records and condense them into memory. Owner or admin only.

contextely actions

MCP tool: actions_list

List the actions you may invoke. Only enabled ones your key's write scopes cover appear.

contextely preview <action> [--arg k=v ...]

MCP tool: action_preview

Show what invoking an action would do. Calls nothing upstream and changes nothing.

contextely invoke <action> --idempotency-key KEY [--arg k=v ...]

MCP tool: action_invokemetered: action

Perform an action. The idempotency key is required, because a generated one is not a replay guard.

contextely discover <source-id>

Ask a source what it can be asked to do. Proposes actions; enables none. Owner or admin only.

contextely runs [--limit N]

The action audit trail: every invocation that ran, and every one that was refused.

contextely approve <action-run-id>

Release an action that was held for a person. Owner or admin only.

contextely reject <action-run-id>

Reject a held action. Nothing upstream is contacted.

A worked example

Search, then follow the thread, then pull the whole record when the summary is not enough. Three calls, and only the third one costs a source round-trip.

$ ./contextely search "acme renewal commitments" --limit 3
1. Acme Industrial: renewal terms  [0.912]
   Renews 2027-01-31 at $48,000/yr on the Growth plan...
   source crm_postgres  refreshed (ttl 900s, read 2026-08-19T08:14:02Z)
   cite crm.internal/accounts/acme
   id 9f2c...

asker [email protected] (owner) | considered 41 | returned 3 | 214ms

$ ./contextely related 9f2c...
Neighbours of "Acme Industrial: renewal terms":

1. Q3 churn commitments to Acme  [0.781]
   shares entities: acme industrial | topics: renewal | same source

$ ./contextely expand 9f2c... --json > record.json

Scripting it

--json prints the raw response, unchanged from what the API returned, so it pipes into jq without a parsing layer. Branch on the exit code, never on the text.

# What did this key get withheld from it?
./contextely search "compensation" --json \
  | jq '.entitlement.withheld_for_entitlement'

# Fail a CI job if anything served was unverifiable.
./contextely search "$QUERY" --json \
  | jq -e '[.results[].freshness.state] | all(. != "stale_refresh_failed")'

# Nightly sync from cron, against a self-hosted deployment.
CONTEXTELY_URL=https://contextely.internal \
  ./contextely ingest "$SOURCE_ID" --limit 200

Exit codes

0	Success.
1	A usage error: unknown command, missing argument, no API key. Nothing was sent.
2	The API refused the call. The error code and message are on stderr.
3	quota_exceeded. A script should back off or upgrade, not retry.
4	The deployment could not be reached at all. A transport failure, not an empty result.
5	The response was not JSON. Usually a proxy in the way rather than Contextely.

Self-hosted deployments

The CLI talks to https://www.contextely.com unless told otherwise. Point it at your own deployment once and it stays pointed.

# Your deployment serves its own copy of the CLI.
curl -fsSL https://contextely.internal/cli.mjs -o contextely && chmod +x contextely

./contextely config set-url https://contextely.internal
./contextely config set-key ctx_sk_...
./contextely search "acme renewal"

# or per call, or from the environment
CONTEXTELY_URL=https://contextely.internal ./contextely usage

The same operations over MCP and HTTP, and the quickstart if you have not connected a source yet. Source for the CLI is in cli/ of the repository.