diff --git a/README.md b/README.md
index 6eb8d6ccc..aa4201243 100644
--- a/README.md
+++ b/README.md
@@ -98,14 +98,88 @@ All sync happens peer-to-peer via [Trystero](https://github.com/dmotz/trystero).
 
 ## CLI
 
-Headless .fig file operations — no GUI needed:
+```sh
+bun add -g @open-pencil/cli
+```
+
+### Inspect .fig files
+
+Browse node trees, search by name or type, dig into properties — all without opening the editor:
 
 ```sh
-bunx @open-pencil/cli info design.fig         # Document stats, node types, fonts
-bunx @open-pencil/cli tree design.fig         # Visual node tree
-bunx @open-pencil/cli find design.fig --type TEXT  # Search by name or type
-bunx @open-pencil/cli export design.fig       # Render to PNG
-bunx @open-pencil/cli export design.fig -f jpg -s 2 -q 90  # JPG at 2x
+open-pencil tree design.fig
+open-pencil find design.fig --type TEXT
+open-pencil node design.fig --id 1:23
+open-pencil info design.fig
+```
+
+```
+[0] [page] "Getting started" (0:46566)
+  [0] [section] "" (0:46567)
+    [0] [frame] "Body" (0:46568)
+      [0] [frame] "Introduction" (0:46569)
+        [0] [frame] "Introduction Card" (0:46570)
+          [0] [frame] "Guidance" (0:46571)
+```
+
+### Export
+
+Render to PNG, JPG, WEBP, SVG — or export as JSX with Tailwind utility classes:
+
+```sh
+open-pencil export design.fig                          # PNG
+open-pencil export design.fig -f jpg -s 2 -q 90       # JPG at 2x, quality 90
+open-pencil export design.fig -f jsx --style tailwind  # Tailwind JSX
+```
+
+```html
+<div className="flex flex-col gap-4 p-6 bg-white rounded-xl">
+  <p className="text-2xl font-bold text-[#1D1B20]">Card Title</p>
+  <p className="text-sm text-[#49454F]">Description text</p>
+</div>
+```
+
+### Analyze design tokens
+
+Audit an entire design system from the terminal — find inconsistencies, extract the real palette, spot components waiting to be extracted:
+
+```sh
+open-pencil analyze colors design.fig
+open-pencil analyze typography design.fig
+open-pencil analyze spacing design.fig
+open-pencil analyze clusters design.fig
+```
+
+```
+#1d1b20  ██████████████████████████████ 17155×
+#49454f  ██████████████████████████████ 9814×
+#ffffff  ██████████████████████████████ 8620×
+#6750a4  ██████████████████████████████ 3967×
+
+3771× frame "container" (100% match)
+     size: 40×40, structure: Frame > [Frame]
+
+2982× instance "Checkboxes" (100% match)
+     size: 48×48, structure: Instance > [Frame]
+```
+
+### Script with Figma Plugin API
+
+`eval` gives you the full Figma Plugin API. Modify the file, write it back:
+
+```sh
+open-pencil eval design.fig -c "figma.currentPage.children.length"
+open-pencil eval design.fig -c "figma.currentPage.selection.forEach(n => n.opacity = 0.5)" -w
+```
+
+### Control the running app
+
+When the desktop app is running, omit the file argument — the CLI connects via RPC and operates on the live canvas. Useful for automation scripts, CI pipelines, or AI agents that need to interact with the editor:
+
+```sh
+open-pencil tree                               # Inspect the live document
+open-pencil export -f png                      # Screenshot the current canvas
+open-pencil eval -c "figma.currentPage.name"   # Query the editor
 ```
 
 All commands support `--json` for machine-readable output.