dotfiles/.agents/skills/cloudflare-deploy/references/kv/configuration.md

KV Configuration

Create Namespace

wrangler kv namespace create MY_NAMESPACE
# Output: { binding = "MY_NAMESPACE", id = "abc123..." }

wrangler kv namespace create MY_NAMESPACE --preview  # For local dev

Workers Binding

wrangler.jsonc:

{
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "abc123xyz789"
    },
    // Optional: Different namespace for preview/development
    {
      "binding": "MY_KV",
      "preview_id": "preview-abc123"
    }
  ]
}

TypeScript Types

env.d.ts:

interface Env {
  MY_KV: KVNamespace;
  SESSIONS: KVNamespace;
  CACHE: KVNamespace;
}

worker.ts:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // env.MY_KV is now typed as KVNamespace
    const value = await env.MY_KV.get("key");
    return new Response(value || "Not found");
  }
} satisfies ExportedHandler<Env>;

Type-safe JSON operations:

interface UserProfile {
  name: string;
  email: string;
  role: "admin" | "user";
}

const profile = await env.USERS.get<UserProfile>("user:123", "json");
// profile: UserProfile | null (type-safe!)
if (profile) {
  console.log(profile.name); // TypeScript knows this is a string
}

CLI Operations

# Put
wrangler kv key put --binding=MY_KV "key" "value"
wrangler kv key put --binding=MY_KV "key" --path=./file.json --ttl=3600

# Get
wrangler kv key get --binding=MY_KV "key"

# Delete
wrangler kv key delete --binding=MY_KV "key"

# List
wrangler kv key list --binding=MY_KV --prefix="user:"

# Bulk operations (max 10,000 keys per file)
wrangler kv bulk put data.json --binding=MY_KV
wrangler kv bulk get keys.json --binding=MY_KV
wrangler kv bulk delete keys.json --binding=MY_KV --force

Local Development

wrangler dev                # Local KV (isolated)
wrangler dev --remote       # Remote KV (production)

# Or in wrangler.jsonc:
# "kv_namespaces": [{ "binding": "MY_KV", "id": "...", "remote": true }]

REST API

Single Operations

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiEmail: process.env.CLOUDFLARE_EMAIL,
  apiKey: process.env.CLOUDFLARE_API_KEY
});

// Single key operations
await client.kv.namespaces.values.update(namespaceId, 'key', {
  account_id: accountId,
  value: 'value',
  expiration_ttl: 3600
});

Bulk Operations

// Bulk update (up to 10,000 keys, max 100MB total)
await client.kv.namespaces.bulkUpdate(namespaceId, {
  account_id: accountId,
  body: [
    { key: "key1", value: "value1", expiration_ttl: 3600 },
    { key: "key2", value: "value2", metadata: { version: 1 } },
    { key: "key3", value: "value3" }
  ]
});

// Bulk get (up to 100 keys)
const results = await client.kv.namespaces.bulkGet(namespaceId, {
  account_id: accountId,
  keys: ["key1", "key2", "key3"]
});

// Bulk delete (up to 10,000 keys)
await client.kv.namespaces.bulkDelete(namespaceId, {
  account_id: accountId,
  keys: ["key1", "key2", "key3"]
});