# Storage Commands

Manage Key-Value, S3, Vector, Database, and Stream storage from the CLI.

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

> [!NOTE]
> **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.

> [!NOTE]
> **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:

```bash
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

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

### Set a Value

```bash
# 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

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

### List Keys

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

### Search Keys

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

### View Statistics

```bash
# 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.

```bash
# 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](/services/storage/key-value).

## 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

```bash
agentuity cloud storage create
# or: agentuity cloud s3 create
```

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

### List Storage Resources

```bash
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

```bash
agentuity cloud s3 upload ./local-file.pdf
```

### Download a File

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

### Get Storage Details

```bash
agentuity cloud s3 get <storage-id>
```

### Delete Storage Resource

```bash
agentuity cloud s3 delete <storage-id>
```

**In agents:** Use Bun's `s3` API (`import { s3 } from "bun"`). See [Object Storage (S3)](/services/storage/object).

## Vector Storage

Search and inspect vector embeddings.

### Search by Similarity

```bash
# 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

```bash
agentuity cloud vec get <namespace> <key>
```

### Upsert Vectors

Add or update vectors from a JSON file:

```bash
# Upsert from file
agentuity cloud vector upsert products --file vectors.json

# File format: array of { key, document?, embeddings?, metadata? }
```

Example `vectors.json`:

```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

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

### View Statistics

```bash
# 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

```bash
agentuity cloud vector namespaces
```

### Delete a Namespace

Delete an entire namespace and all its vectors:

```bash
agentuity cloud vector delete-namespace old-products
```

> [!WARNING]
> **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](/services/storage/vector).

## Database

Manage database resources and run SQL queries.

### List Databases

```bash
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

```bash
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

```bash
agentuity cloud db get <database-id>
```

### Run SQL Queries

Execute SQL queries directly from the CLI:

```bash
# 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

```bash
agentuity cloud db logs <database-id>
```

### Delete a Database

```bash
agentuity cloud db delete <database-id>
```

**In agents:** Use Bun's `sql` API (`import { sql } from "bun"`). See [Database](/services/database/overview).

## Streams

List and manage durable event streams.

### List Streams

```bash
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 |

> [!WARNING]
> **Mutual Exclusivity**
> `--org-id` and `--project-id` cannot be used together. Use one or the other.

### Get Stream Details

```bash
agentuity cloud stream get <stream-id>
```

### Delete a Stream

```bash
agentuity cloud stream delete <stream-id>
```

**In agents:** Use `ctx.stream` for programmatic access. See [Durable Streams](/services/storage/durable-streams).

## Redis

View Redis connection details for your organization.

### Show Connection URL

```bash
# 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
```

> [!NOTE]
> **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`:

```bash
REDIS_URL=redis://...
```

## Next Steps

- [Configuration Commands](/reference/cli/configuration): Manage environment variables, secrets, and API keys
- [Key-Value Storage](/services/storage/key-value): Programmatic KV access in agents
- [Object Storage (S3)](/services/storage/object): File storage with Bun S3
- [Database](/services/database/overview): SQL queries with Bun SQL
- [Vector Storage](/services/storage/vector): Semantic search in agents