diff --git a/packages/web/src/content/docs/cli.mdx b/packages/web/src/content/docs/cli.mdx
index 64e11ff5627..777d377a723 100644
--- a/packages/web/src/content/docs/cli.mdx
+++ b/packages/web/src/content/docs/cli.mdx
@@ -161,13 +161,32 @@ opencode github run
 List all available models from configured providers.
 
 ```bash
-opencode models
+opencode models [provider]
 ```
 
 This command displays all models available across your configured providers in the format `provider/model`.
 
 This is useful for figuring out the exact model name to use in [your config](/docs/config/).
 
+You can optionally pass a provider ID to filter models by that provider.
+
+```bash
+opencode models anthropic
+```
+
+#### Flags
+
+| Flag        | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `--refresh` | Refresh the models cache from models.dev                     |
+| `--verbose` | Use more verbose model output (includes metadata like costs) |
+
+Use the `--refresh` flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in OpenCode.
+
+```bash
+opencode models --refresh
+```
+
 ---
 
 ### run