Agentuity Documentation

These CLI commands help you inspect and manage cloud storage during development and debugging.

Cloud Prefix Required

All storage commands require the cloud prefix. For example: agentuity cloud kv get ...

Key-Value Storage

Inspect and manage key-value data organized into namespaces.

Organization-Scoped

KV storage is scoped to your organization, not individual projects. You can run KV commands from any directory without needing a project context.

Interactive REPL

Start an interactive session for faster exploration:

agentuity cloud kv repl

In the REPL, use commands like set, get, delete, keys, and stats:

> set cache user:123 '{"name":"Alice"}'
> get cache user:123
> keys cache
> stats

Get a Value

agentuity cloud kv get production user:123
agentuity cloud kv get cache session:abc

Set a Value

# Store JSON data
agentuity cloud kv set production user:123 '{"name":"Alice","email":"alice@example.com"}'
 
# Set with TTL (expires after 1 hour)
agentuity cloud kv set cache session:abc "session-data" --ttl 3600

Delete a Key

agentuity cloud kv delete production user:123
agentuity cloud kv rm cache session:abc  # Using alias

List Keys

agentuity cloud kv keys production
agentuity cloud kv ls cache  # Using alias

Search Keys

agentuity cloud kv search production user
agentuity cloud kv search cache session

View Statistics

# Stats for all namespaces
agentuity cloud kv stats
 
# Stats for specific namespace
agentuity cloud kv stats production
 
# Filter by name
agentuity cloud kv stats --name cache
 
# Sort by size, largest first
agentuity cloud kv stats --sort=size --direction=desc
 
# Paginate results
agentuity cloud kv stats --limit=10 --offset=20
 
# Filter by project or agent
agentuity cloud kv stats --project-id=proj_abc --agent-id=agt_xyz

Option	Description
`--name <name>`	Filter namespaces by name
`--sort <field>`	Sort by `name`, `size`, `records`, `created`, or `lastUsed` (default: `name`)
`--direction <dir>`	Sort direction: `asc` or `desc` (default: `asc`)
`--limit <n>`	Maximum number of results
`--offset <n>`	Pagination offset
`--project-id <id>`	Filter by project ID
`--agent-id <id>`	Filter by agent ID
`--project-name <name>`	Filter by project name
`--agent-name <name>`	Filter by agent name

Sort field values are case-sensitive and use camelCase (e.g., --sort=lastUsed, not --sort=last-used).

Namespace Management

A namespace is a logical container that groups related keys together. For example, you might use cache for temporary data, users for user profiles, and sessions for session state.

# List all namespaces
agentuity cloud kv list-namespaces
agentuity cloud kv ns  # Using alias
 
# Create a namespace
agentuity cloud kv create-namespace staging
 
# Delete a namespace and all its keys
agentuity cloud kv delete-namespace old-cache

In agents: Use ctx.kv for programmatic access. See Key-Value Storage.

S3 Storage

Manage S3-compatible storage resources for file uploads and downloads.

Both cloud storage and cloud s3 work interchangeably. Examples below use s3 for brevity.

Create Storage Resource

agentuity cloud storage create
# or: agentuity cloud s3 create

This adds S3 credentials to your local .env file automatically.

List Storage Resources

agentuity cloud s3 list
 
# Filter by name
agentuity cloud s3 list --name my-bucket
 
# Sort by name
agentuity cloud s3 list --sort=name --direction=asc
 
# Paginate results
agentuity cloud s3 list --limit=10 --offset=0

Option	Description
`--name <name>`	Filter by bucket name
`--sort <field>`	Sort by `name`, `created`, or `region` (default: `created`)
`--direction <dir>`	Sort direction: `asc` or `desc` (default: `desc`)
`--limit <n>`	Maximum number of results
`--offset <n>`	Pagination offset
`--org-id <id>`	Filter by organization
`--show-credentials`	Show credentials in plain text (masked by default)
`--name-only`	Print only the bucket name

Upload a File

agentuity cloud s3 upload ./local-file.pdf

Download a File

agentuity cloud s3 download <file-id> --output ./downloaded-file.pdf

Get Storage Details

agentuity cloud s3 get <storage-id>

Delete Storage Resource

agentuity cloud s3 delete <storage-id>

In agents: Use Bun's s3 API (import { s3 } from "bun"). See Object Storage (S3).

Vector Storage

Search and inspect vector embeddings.

Search by Similarity

# Basic search
agentuity cloud vector search products "comfortable office chair"
 
# Limit results
agentuity cloud vector search docs "API documentation" --limit 5
 
# Set minimum similarity threshold
agentuity cloud vector search products "ergonomic" --similarity 0.8
 
# Filter by metadata
agentuity cloud vector search embeddings "neural networks" --metadata category=ai

Get Vector by ID

agentuity cloud vec get <namespace> <key>

Upsert Vectors

Add or update vectors from a JSON file:

# Upsert from file
agentuity cloud vector upsert products --file vectors.json
 
# File format: array of { key, document?, embeddings?, metadata? }

Example vectors.json:

[
  {
    "key": "product-123",
    "document": "Ergonomic office chair with lumbar support",
    "metadata": { "category": "furniture", "price": 299 }
  },
  {
    "key": "product-456",
    "document": "Standing desk with adjustable height",
    "metadata": { "category": "furniture", "price": 599 }
  }
]

Delete a Vector

agentuity cloud vec delete <namespace> <key> [<key>...]

View Statistics

# Stats for all namespaces
agentuity cloud vector stats
 
# Stats for specific namespace
agentuity cloud vector stats products
 
# Filter by name
agentuity cloud vector stats --name embeddings
 
# Sort by record count, descending
agentuity cloud vector stats --sort=records --direction=desc
 
# Paginate results
agentuity cloud vector stats --limit=10 --offset=0

Option	Description
`--name <name>`	Filter namespaces by name
`--sort <field>`	Sort by `name`, `size`, `records`, `created`, or `lastUsed` (default: `name`)
`--direction <dir>`	Sort direction: `asc` or `desc` (default: `asc`)
`--limit <n>`	Maximum number of results
`--offset <n>`	Pagination offset

List Namespaces

agentuity cloud vector namespaces

Delete a Namespace

Delete an entire namespace and all its vectors:

agentuity cloud vector delete-namespace old-products

Destructive Operation

Deleting a namespace removes all vectors within it. This cannot be undone.

In agents: Use ctx.vector for programmatic access. See Vector Storage.

Database

Manage database resources and run SQL queries.

List Databases

agentuity cloud db list
 
# Filter by name
agentuity cloud db list --name analytics-db
 
# Sort by name, ascending
agentuity cloud db list --sort=name --direction=asc
 
# Paginate results
agentuity cloud db list --limit=10 --offset=0

Option	Description
`--name <name>`	Filter by database name
`--sort <field>`	Sort by `name`, `created`, or `region` (default: `created`)
`--direction <dir>`	Sort direction: `asc` or `desc` (default: `desc`)
`--limit <n>`	Maximum number of results
`--offset <n>`	Pagination offset
`--org-id <id>`	Filter by organization
`--show-credentials`	Show credentials in plain text (masked by default)
`--name-only`	Print only the database name

Create a Database

agentuity cloud db create --name my-database
agentuity cloud db create --name analytics-db --description "Analytics data warehouse"

Option	Description
`--name <name>`	Custom database name
`--description <text>`	Optional database description

This adds DATABASE_URL to your local .env file automatically.

Get Database Details

agentuity cloud db get <database-id>

Run SQL Queries

Execute SQL queries directly from the CLI:

# Simple query
agentuity cloud db sql "SELECT * FROM users LIMIT 10"
 
# Query with filtering
agentuity cloud db sql "SELECT name, email FROM users WHERE active = true"
 
# Insert data
agentuity cloud db sql "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"

View Database Logs

agentuity cloud db logs <database-id>

Delete a Database

agentuity cloud db delete <database-id>

In agents: Use Bun's sql API (import { sql } from "bun"). See Database.

Streams

List and manage durable event streams.

List Streams

agentuity cloud stream list
 
# Filter by namespace
agentuity cloud stream list --namespace agent-logs
 
# Filter by metadata
agentuity cloud stream list --metadata type=export
 
# Sort by size, largest first
agentuity cloud stream list --sort=size --direction=desc
 
# Paginate results (uses --size for limit, not --limit)
agentuity cloud stream list --size=50 --offset=10
 
# Filter by project or organization
agentuity cloud stream list --project-id=proj_abc123
agentuity cloud stream list --org-id=org_abc123

Option	Description
`--size <n>`	Maximum number of streams to return (default: `100`)
`--offset <n>`	Pagination offset
`--name <name>`	Filter by stream name
`--namespace <ns>`	Filter by namespace
`--metadata <key=value>`	Filter by metadata (comma-separated pairs)
`--sort <field>`	Sort by `name`, `created`, `updated`, `size`, `count`, or `lastUsed` (default: `created`)
`--direction <dir>`	Sort direction: `asc` or `desc` (default: `desc`)
`--project-id <id>`	Filter by project
`--org-id <id>`	Filter by organization

Mutual Exclusivity

--org-id and --project-id cannot be used together. Use one or the other.

Get Stream Details

agentuity cloud stream get <stream-id>

Delete a Stream

agentuity cloud stream delete <stream-id>

In agents: Use ctx.stream for programmatic access. See Durable Streams.

Redis

View Redis connection details for your organization.

Show Connection URL

# Show Redis URL (credentials masked in terminal)
agentuity cloud redis show
 
# Show with credentials visible
agentuity cloud redis show --show-credentials
 
# JSON output (credentials always visible)
agentuity --json cloud redis show

Organization Resource

Redis is provisioned at the organization level. Contact support if you need Redis enabled for your organization.

To use Redis locally, add the URL to your .env:

REDIS_URL=redis://...

Next Steps

Configuration Commands: Manage environment variables, secrets, and API keys
Key-Value Storage: Programmatic KV access in agents
Object Storage (S3): File storage with Bun S3
Database: SQL queries with Bun SQL
Vector Storage: Semantic search in agents