Mason/cli docs organization (#35)

masnwilliams · web-flow · commit 131c6869fd7a · 2025-09-02T12:15:11.000-04:00
* docs(mcp-server): rewrite and clarify setup guide

* docs: Add MCP token reset to troubleshooting

* docs: Enhance CLI documentation with new authentication, browser, and app management sections

* docs(mcp-server): fix formatting for delete_browser command in browser automation section

* docs(mcp-server): update setup instructions and wording

* docs: wrap Claude info in Info block

* docs(mcp-server): update Claude compatibility info
diff --git a/docs.json b/docs.json
@@ -126,7 +126,10 @@
         "tab": "CLI",
         "icon": "terminal",
         "pages": [
-          "reference/cli"
+          "reference/cli",
+          "reference/cli/auth",
+          "reference/cli/browsers",
+          "reference/cli/apps"
         ]
       }
     ]
diff --git a/reference/cli.mdx b/reference/cli.mdx
@@ -6,8 +6,6 @@ The Kernel CLI helps you access and manage your Kernel resources.
 
 ## Installation
 
-Install the Kernel CLI using your favorite package manager:
-
 ```bash
 # Using brew
 brew install onkernel/tap/kernel
@@ -19,94 +17,44 @@ pnpm install -g @onkernel/cli
 npm install -g @onkernel/cli
 ```
 
-## Authentication
-
-The Kernel CLI supports two authentication methods:
-
-### OAuth 2.0 (Recommended)
-
-The preferred method is OAuth 2.0 with PKCE, which provides secure browser-based authentication:
+Verify installation:
 
 ```bash
-kernel login
+which kernel
+kernel --version
 ```
 
-This opens your browser to complete the OAuth flow. Your tokens are securely stored in your system keychain (macOS/Windows) or a local file (Linux).
-
-### API Key
+<Columns cols={2}>
+  <Card icon="key" title="Authentication" href="/reference/cli/auth">
+    Login, logout, and check auth status.
+  </Card>
+  <Card icon="browsers" title="Browsers" href="/reference/cli/browsers">
+    Create, view, and manage Kernel browsers.
+  </Card>
+  <Card icon="rocket" title="Apps" href="/reference/cli/apps">
+    Deploy apps, invoke actions, and stream logs.
+  </Card>
+</Columns>
 
-You can also authenticate using an API key:
+## Quick Start
 
 ```bash
-export KERNEL_API_KEY=<API_KEY>
-```
+# 1) Login
+kernel login
 
-## Verifying installation
-After installation, verify that Kernel CLI was installed correctly:
+# 2) Deploy your app
+kernel deploy index.ts
 
-```bash
-which kernel
+# 3) Invoke your app
+kernel invoke my-app action-name --payload '{"key":"value"}'
 ```
 
 ## Global Flags
 
-| Flag | Description |
-|------|-------------|
-| `--version`, `-v` | Print the CLI version |
-| `--no-color` | Disable color output |
-| `--log-level <level>` | Set the log level (trace, debug, info, warn, error, fatal, print) |
-
-## Authentication Commands
-
-| Command | Description |
-|---------|-------------|
-| `kernel login [--force]` | Initiates OAuth 2.0 authentication flow via browser. Use `--force` to re-authenticate when already logged in |
-| `kernel logout` | Clears stored authentication tokens and logs out |
-| `kernel auth` | Displays current authentication status, user details, and token expiry. Use `--log-level debug` for detailed information including user ID and storage method |
-
-## Browser Management Commands
-
-| Command | Description |
-|---------|-------------|
-| `kernel browsers list` | List running or persistent browsers |
-| `kernel browsers create` | Create a new browser session |
-| | `--persistence-id <id>` | Unique identifier for browser session persistence. Optional. |
-| | `--stealth` | Launch browser in stealth mode to avoid detection. Optional. |
-| | `--headless` | Launch browser without GUI access. Optional. |
-| `kernel browsers delete` | Delete a browser. Must specify either `--by-persistent-id` or `--by-id` |
-| | `--by-persistent-id <id>` | Delete browser by persistent ID |
-| | `--by-id <id>` | Delete browser by session ID |
-| | `--yes`, `-y` | Skip confirmation prompt |
-| `kernel browsers view` | Get the live view URL for a browser. Must specify either `--by-persistent-id` or `--by-id` |
-| | `--by-persistent-id <id>` | View browser by persistent ID |
-| | `--by-id <id>` | View browser by session ID |
-
-## App Management Commands
-
-| Command | Optional Flags | Description |
-|---------|-------------| -------------|
-| `kernel deploy <entrypoint_file_name>` | - | Deploys an app to Kernel from the current directory. |
-| | `--version <version>` | Specify a version for the app (default: latest). Optional. |
-| | `--force` | Allow overwrite of an existing version with the same name. Optional. |
-| | `--env <ENV_VAR=VAL>`, `-e` | Adds environment variables to the app. Expects the form `ENV_VAR=VAL` delimited by spaces. May be specified multiple times. Optional. |
-| | `--env-file <file>` | Read environment variables from a file (.env format). May be specified multiple times. Optional. |
-| `kernel invoke <app_name> <action_name>` | - | Invokes a specific app action by its name. Generates an Invocation. |
-| | `--version <version>`, `-v` | Specify a version of the app to invoke (default: latest). Optional. |
-| | `--payload <payload_data>`, `-p` | Includes the specified parameters. Expects a stringified JSON object. Optional. |
-| | `--sync`, `-s` | Invoke synchronously (default false). A synchronous invocation opens a long-lived HTTP POST that times out after 60 seconds. Optional. |
-| | `ctrl-c` | Terminates the running invocation in your CLI. Also destroys any associated browsers. |
-| `kernel app list` | - | List deployed application versions. |
-| | `--name <app_name>` | Filter by application name. Optional. |
-| | `--version <version>` | Filter by version label. Optional. |
-| `kernel app history <app_name>` | - | Show deployment history for an application. |
-| `kernel logs <app_name>` | - | Prints the logs for the specified app. |
-| | `--version <version>` | Specify a version of the app (default: latest). Optional. |
-| | `--follow`, `-f` | Follow logs in real-time (stream continuously). Optional. |
-| | `--since <time>`, `-s` | How far back to retrieve logs (e.g., 5m, 1h). Defaults to 5m if not following, 5s if following. Optional. |
-| | `--with-timestamps` | Include timestamps in each log line. Optional. |
-
-## General Commands
+- `--version`, `-v` - Print the CLI version
+- `--no-color` - Disable color output
+- `--log-level <level>` - Set the log level (trace, debug, info, warn, error, fatal, print)
 
-| Command | Description |
-|---------|-------------|
-| `kernel help [command]` | Displays help information about Kernel commands |
+<Info>
+Looking for the API? See the [API Reference](/api-reference/invocations/invoke-an-action).
+</Info>
diff --git a/reference/cli/apps.mdx b/reference/cli/apps.mdx
@@ -0,0 +1,45 @@
+---
+title: "Apps"
+---
+
+## `kernel deploy <entrypoint_file_name>`
+Deploy an app to Kernel from the current directory.
+
+| Flag | Description |
+|------|-------------|
+| `--version <version>` | Specify a version for the app (default: latest). Optional. |
+| `--force` | Allow overwrite of an existing version with the same name. Optional. |
+| `--env <ENV_VAR=VAL>`, `-e` | Adds environment variables to the app. May be specified multiple times. Optional. |
+| `--env-file <file>` | Read environment variables from a .env file. May be specified multiple times. Optional. |
+
+## `kernel invoke <app_name> <action_name>`
+Invoke a specific app action by its name. Generates an Invocation.
+
+| Flag | Description |
+|------|-------------|
+| `--version <version>`, `-v` | Specify a version of the app to invoke (default: latest). Optional. |
+| `--payload <payload_data>`, `-p` | Stringified JSON object (max 64 KB). Optional. |
+| `--sync`, `-s` | Invoke synchronously (default false). Optional. |
+
+<Info>Synchronous invocations open a long-lived HTTP POST that times out after 60 seconds. Press `ctrl-c` to terminate a running invocation; associated browsers are destroyed.</Info>
+
+## `kernel app list`
+List deployed application versions.
+
+| Flag | Description |
+|------|-------------|
+| `--name <app_name>` | Filter by application name. Optional. |
+| `--version <version>` | Filter by version label. Optional. |
+
+## `kernel app history <app_name>`
+Show deployment history for an application.
+
+## `kernel logs <app_name>`
+Print the logs for the specified app.
+
+| Flag | Description |
+|------|-------------|
+| `--version <version>` | Specify a version of the app (default: latest). Optional. |
+| `--follow`, `-f` | Follow logs in real-time (stream continuously). Optional. |
+| `--since <time>`, `-s` | How far back to retrieve logs (e.g., 5m, 1h). Defaults to 5m if not following, 5s if following. Optional. |
+| `--with-timestamps` | Include timestamps in each log line. Optional. |
diff --git a/reference/cli/auth.mdx b/reference/cli/auth.mdx
@@ -0,0 +1,20 @@
+---
+title: "Authentication"
+---
+
+## `kernel login`
+Login via OAuth 2.0 (PKCE) using your browser. Credentials are stored securely and refreshed automatically.
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Force re-authentication even if already logged in |
+
+## `kernel logout`
+Clear stored authentication tokens and log out.
+
+## `kernel auth`
+Show current authentication status and token expiry.
+
+| Flag | Description |
+|------|-------------|
+| `--log-level debug` | Set the log level to debug for detailed info including user ID, org ID, and storage method. |
diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx
diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx

Original file line number	Diff line number	Diff line change
`@@ -126,7 +126,10 @@`
`126`	`126`	`"tab": "CLI",`
`127`	`127`	`"icon": "terminal",`
`128`	`128`	`"pages": [`
`129`		`- "reference/cli"`
	`129`	`+ "reference/cli",`
	`130`	`+ "reference/cli/auth",`
	`131`	`+ "reference/cli/browsers",`
	`132`	`+ "reference/cli/apps"`
`130`	`133`	`]`
`131`	`134`	`}`
`132`	`135`	`]`