From 69e4464ad69468b8113f6d7d0bb34291a884ad55 Mon Sep 17 00:00:00 2001
From: hev <adam.hevenor@gmail.com>
Date: Wed, 14 Jan 2026 06:34:39 -0700
Subject: [PATCH] Add schema commands documentation to README

Document the schema get, apply, and copy subcommands with usage
examples, options, and example schema file format.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/README.md b/README.md
index 6854114..7bb2ae3 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,85 @@ tpuff edit <document-id> -n my-namespace
 ```
 This will open the document in vim. Save and quit (`:wq`) to upsert changes, or quit without saving (`:q!`) to cancel.
 
+### schema
+
+Manage namespace schemas. Schemas define attribute types and indexing options for your namespaces.
+
+#### schema get
+
+Display the schema for a namespace:
+```bash
+tpuff schema get -n my-namespace
+```
+
+**Options:**
+- `-n, --namespace <name>`: Namespace to get schema from (required)
+- `-r, --region <region>`: Override the region
+- `--raw`: Output raw JSON without formatting (for piping)
+
+#### schema apply
+
+Apply a schema from a JSON file to one or more namespaces:
+
+**Apply to a single namespace:**
+```bash
+tpuff schema apply -n my-namespace -f schema.json
+```
+
+**Apply to namespaces matching a prefix:**
+```bash
+tpuff schema apply --prefix my-namespace- -f schema.json
+```
+
+**Apply to all namespaces:**
+```bash
+tpuff schema apply --all -f schema.json
+```
+
+**Preview changes without applying (dry run):**
+```bash
+tpuff schema apply -n my-namespace -f schema.json --dry-run
+```
+
+The command shows a diff of schema changes before applying. Type changes to existing attributes are not allowed and will be flagged as conflicts.
+
+**Options:**
+- `-n, --namespace <name>`: Target namespace to apply schema to
+- `--prefix <prefix>`: Apply to all namespaces matching this prefix
+- `--all`: Apply to all namespaces
+- `-f, --file <path>`: JSON file containing schema definition (required)
+- `-r, --region <region>`: Override the region
+- `--dry-run`: Show diff only, don't apply changes
+- `-y, --yes`: Skip confirmation prompt
+- `--continue-on-error`: Continue applying to other namespaces when conflicts occur (batch mode only)
+
+**Example schema file (`schema.json`):**
+```json
+{
+  "title": "string",
+  "embedding": "[1536]f32",
+  "content": {"type": "string", "full_text_search": true},
+  "category": {"type": "string", "filterable": true}
+}
+```
+
+Valid types: `string`, `uint64`, `uuid`, `bool`, or vector format `[dims]f32`/`[dims]f16`.
+
+#### schema copy
+
+Copy a schema from an existing namespace to a new namespace:
+```bash
+tpuff schema copy -n source-namespace --to target-namespace
+```
+
+The target namespace must be empty or non-existent. A placeholder row will be created to initialize the namespace with the schema.
+
+**Options:**
+- `-n, --namespace <name>`: Source namespace to copy schema from (required)
+- `--to <name>`: Target namespace name (required)
+- `-r, --region <region>`: Override the region
+- `-y, --yes`: Skip confirmation prompt
+
 ## Development
 
 ```bash