Data and messaging

This page documents the four service command groups: serverless, pubsub, memorystore, and vectordb. They inspect the platform's managed data and messaging services, and — for pub/sub — publish and pull messages.

How these groups behave

The four groups share rules that differ from the rest of the CLI:

They require a project. There is no server-side default here. If no project resolves from --project, $CAI_PROJECT, or your saved config default, the command fails with:

this command needs a project: pass --project, set $CAI_PROJECT, or run 'platformctl config set-project' (use the id or slug shown by 'platformctl projects list')

A project UUID is used directly with no lookup call (good for CI). A slug or short name costs one GET /v1/projects lookup; if nothing matches:

no project matches "my-proj" among the projects you can access (see 'platformctl projects list')

They do not take their base URL from --api. Each group talks to its own service and has its own endpoint override; otherwise it auto port-forwards, just like the control plane. One caveat: a slug or short-name --project is resolved to its UUID through agent-engine-api, which is reached via --api, $CAI_API, or a port-forward. Pass the project's UUID (from platformctl projects list) to make these commands fully independent of the control plane:

Group	Env override	Port-forward target
serverless	CAI_SERVERLESS_API	svc/serverless-api in cai-system
pubsub	CAI_PUBSUB_API	svc/pubsub-api in cai-system
memorystore	CAI_MEMORYSTORE_API	svc/memorystore-api in cai-system
vectordb	CAI_VECTORDB_API	svc/vectordb-api in cai-system

They are inspection-first. The CLI can list and read these resources, and publish/pull pub/sub messages. It cannot create or delete any of them — there is no platformctl vectordb create. Creating topics, subscriptions, memory stores, vector indexes, and serverless services is console/API only. All list commands follow pagination to the end.

---

platformctl serverless

Read-only inspection of serverless container services. Deploy and edit them through the console or the API — see deploy a service and the serverless API reference.

serverless list

platformctl serverless list

platformctl serverless list

You should see a table with the columns NAME, PHASE, PUBLISHED, and URL. The URL column prefers the service's external URL when it has one.

serverless get

platformctl serverless get <name>

platformctl serverless get my-service -o json

You should see the full service object as JSON. Use -o json whenever you need fields the table omits.

---

platformctl pubsub topics

Inspect topics and publish messages. A topic is a named channel that producers publish messages to; subscriptions deliver those messages to consumers. To create topics or subscriptions, use the console or the API — see topics and subscriptions.

pubsub topics list

platformctl pubsub topics list

platformctl pubsub topics list

You should see a table with the columns NAME, READY, PHASE, and PUBLISHED.

pubsub topics get

platformctl pubsub topics get <topic>

platformctl pubsub topics get orders -o json

You should see the full topic object as JSON.

pubsub topics publish

platformctl pubsub topics publish <topic> --message <text|@file|-> [--attribute KEY=VALUE ...]

Flag	Default	What it does
--message	none — required	The message body: a literal string, @path to read a file, or - to read stdin.
--attribute	none	A KEY=VALUE metadata pair attached to the message. Repeat the flag for more attributes.

Missing --message fails with:

--message is required (a literal string, @file, or - for stdin)

A malformed attribute fails with:

--attribute "region" must be KEY=VALUE

Example:

platformctl pubsub topics publish orders --message '{"order_id": 42}' --attribute region=eu -o json

You should see the id of each stored message:

{"message_ids": ["..."]}

If the server stores only some of the batch, the CLI reports:

partial publish: 1 of 2 stored (<error>)

Publishing from a file or stdin

platformctl pubsub topics publish orders --message @order.json
echo '{"order_id": 43}' | platformctl pubsub topics publish orders --message -

---

platformctl pubsub subscriptions

Inspect subscriptions and pull messages. Subscriptions are nested under a topic, so every command in this group requires --topic:

--topic is required (subscriptions are nested under a topic)

pubsub subscriptions list

platformctl pubsub subscriptions list --topic <topic>

platformctl pubsub subscriptions list --topic orders

You should see a table with the columns NAME, TOPIC, TYPE, READY, and BACKLOG.

pubsub subscriptions get

platformctl pubsub subscriptions get <sub> --topic <topic>

platformctl pubsub subscriptions get orders-worker --topic orders -o json

You should see the full subscription object as JSON.

pubsub subscriptions pull

Fetches waiting messages from a subscription.

platformctl pubsub subscriptions pull <sub> --topic <topic> [--max <n>] [--ack]

Flag	Default	What it does
--max	server default 10, cap 100	Maximum messages to pull.
--ack	off	Acknowledge the pulled messages, so they are not delivered again.

Example:

platformctl pubsub subscriptions pull orders-worker --topic orders --max 10 --ack -o json

You should see the pull response on stdout:

{"messages": [{"ack_id": "...", "id": "...", "data": "eyJvcmRlcl9pZCI6IDQyfQ==", "key": ""}]}

and, because of --ack, a confirmation on stderr:

acknowledged 1 message(s)

Pull without --ack does not consume

Pulled messages that are not acknowledged are redelivered after the acknowledgment deadline. Pass --ack when you mean "take these off the queue."

Notes:

• --ack issues a separate acknowledge call after the pull. Its confirmation goes to stderr so stdout stays the exact pull response for scripting.
• If acknowledging fails after a successful pull:

pulled 1 message(s) but acknowledging them failed (they will redeliver): ...

• The default table output decodes message payloads for you; -o json and -o yaml carry the exact base64 as returned (in the example above, data decodes to {"order_id": 42}).

See also: publish and consume and the pub/sub API reference.

---

platformctl memorystore

Read-only inspection of memory stores (managed Valkey instances — an in-memory key-value database, protocol-compatible with Redis). Creation is console/API only — see the memory store quickstart.

memorystore list

platformctl memorystore list

platformctl memorystore list

You should see a table with the columns NAME, SIZE_CLASS, STATE, and READY.

memorystore get

platformctl memorystore get <name>

platformctl memorystore get session-cache -o json

You should see the full memory store object as JSON.

memorystore stats

platformctl memorystore stats <name>

platformctl memorystore stats session-cache

You should see a live statistics snapshot from the store itself (a Valkey INFO snapshot): used memory, operation counts, and similar runtime figures. The response never discloses the store's credential — see connect from workloads for how workloads get access.

---

platformctl vectordb

Read-only inspection of vector indexes (searchable stores of embeddings — lists of numbers that represent meaning, so similar text lands near similar text). Creating indexes, and upserting or searching points, is console/API only — see the vector database quickstart and collections and points.

vectordb list

platformctl vectordb list

platformctl vectordb list

You should see a table with the columns NAME, DIMENSIONS, DISTANCE, STATE, READY, and POINTS.

vectordb get

platformctl vectordb get <name>

platformctl vectordb get product-embeddings -o json

You should see the full index object as JSON.

See also: the vector database API reference.