> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Preview a CLI surface

GET https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/cli/preview

Renders the saved `cli` surface the way a publish would build it: the exact `--help` text of the CLI and of each command, each command's flags and an example, and the SKILL.md. Compares that build with the version the install host serves, listing added, removed and changed commands and changed settings. Reads the install host's bucket and never writes to it; a surface that is turned off still previews.

Reference: https://docs.runtype.com/api-reference/runtype-api/products/preview-a-cli-surface

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `productId` (string, required)
- `surfaceId` (string, required)

## Response

### 200

Preview

- `binName` (string, required) — The command name the preview renders, which is also the install slug
- `builtins` (list of CliPreviewBuiltinsItems, required) — The built-in commands every CLI has, as `--help` lists them
- `commands` (list of CliPreviewCommand, required) — One entry per tool command, hidden ones included, sorted by command path
- `displayName` (string, required) — The name `--help` opens with: the product name
- `help` (string, required) — The exact text `<bin> --help` prints
- `publish` (CliPreviewPublish, required)
- `skill` (string, required) — The SKILL.md a publish writes and `<bin> skill install` installs

## Errors

### 400 Bad Request Error

Invalid IDs, no valid command name (`CLI_BIN_NAME_REQUIRED`) or a name the publish refuses (`CLI_NAME_REJECTED`)

- `error` (string, required)
- `code` (string, optional)
- `issues` (list of V1ProductsProductIdSurfacesSurfaceIdCliPreviewGetResponsesContentApplicationJsonSchemaIssuesItems, optional)

### 403 Forbidden Error

Insufficient permissions, `CLI_SURFACE_PUBLISH_DISABLED` while publishing is off for the account, or `CLI_INSTALL_DOMAIN_DISABLED` for an install domain while custom install domains are off

- `error` (string, required)
- `code` (string, optional)
- `issues` (list of V1ProductsProductIdSurfacesSurfaceIdCliPreviewGetResponsesContentApplicationJsonSchemaIssuesItems, optional)

### 404 Not Found Error

Product or CLI surface not found

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 502 Bad Gateway Error

`CLI_DIST_UNAVAILABLE`: the install host's storage failed

- `error` (string, required)
- `code` (string, optional)
- `issues` (list of V1ProductsProductIdSurfacesSurfaceIdCliPreviewGetResponsesContentApplicationJsonSchemaIssuesItems, optional)

### 503 Service Unavailable Error

`CLI_DIST_NOT_CONFIGURED`: this deployment has no `CLI_DIST` bucket or install host

- `error` (string, required)
- `code` (string, optional)
- `issues` (list of V1ProductsProductIdSurfacesSurfaceIdCliPreviewGetResponsesContentApplicationJsonSchemaIssuesItems, optional)

## Types

### CliPreviewBuiltinsItems

- `command` (string, required)
- `description` (string, required)

### CliPreviewCommand

- `aliases` (list of string, required) — Other paths that reach the command, e.g. the hyphenated name
- `callOnly` (boolean, required) — The tool shares its name with a built-in, so only `<bin> call <tool>` reaches it
- `command` (string, required) — The command path after the command name, e.g. `search_tickets` or `call login`
- `example` (string, required) — A runnable example invocation with every required flag
- `flags` (list of CliPreviewFlag, required) — The flags `<bin> <command> --help` lists, in order
- `help` (string, required) — The exact text `<bin> <command> --help` prints
- `hidden` (boolean, required) — A command override hides it from `--help`; it still runs
- `placeholderDescription` (boolean, required) — The description is the `Execute the <tool> capability` default a capability without a description gets
- `summary` (string, required) — The first sentence of the description, as `--help` lists it
- `tool` (string, required) — The MCP tool the command calls
- `usage` (string, required) — The usage line, e.g. `acme search_tickets <query> [flags]`

### CliPreviewPublish

- `changes` (CliPreviewPublishChanges, required, nullable) — What a publish would change; null while unpublished
- `digest` (string, required) — The digest a publish of the saved surface would record
- `publishedAt` (string, required, nullable)
- `publishedDigest` (string, required, nullable) — The digest the published version recorded; null while unpublished
- `state` (enum, required) — `unpublished`: the install host serves nothing for this surface. `published`: it serves exactly what a publish would write now. `changesNotPublished`: the saved surface differs from the published version.
  - Allowed values: `unpublished`, `published`, `changesNotPublished`
- `version` (string, required, nullable) — The published version; null while unpublished

### V1ProductsProductIdSurfacesSurfaceIdCliPreviewGetResponsesContentApplicationJsonSchemaIssuesItems

- `code` (string, required)
- `message` (string, required)
- `verdict` (enum, required)
  - Allowed values: `review`, `reject`

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### CliPreviewFlag

- `description` (string, required) — The first sentence of the argument's description; empty when it has none
- `name` (string, required) — The flag without its leading `--`, e.g. `ticket-id`
- `positional` (boolean, required) — Also accepted as a positional argument
- `repeatable` (boolean, required) — Takes the flag more than once, one value each time
- `required` (boolean, required)
- `type` (string, required) — A TypeScript-style type, as the signature line prints it, e.g. `"open" | "closed"`
- `wire` (string, required) — The tool argument the flag sets, e.g. `ticketId`
- `default` (any, optional) — The schema default, when it declares one
- `enum` (list of any, optional) — The accepted values of an enum argument

### CliPreviewPublishChanges

What a publish would change; null while unpublished

- `commandsAdded` (list of CliPreviewPublishChangesCommandsAddedItems, required)
- `commandsChanged` (list of CliPreviewPublishChangesCommandsChangedItems, required)
- `commandsRemoved` (list of CliPreviewPublishChangesCommandsRemovedItems, required)
- `settings` (list of enum, required) — `binName`: the published version is under another command name. `installDomain`: the requested install domain differs from the last publish. `other`: the files differ in a way no listed setting or command explains, such as a newer installer.
  - Allowed values: `binName`, `displayName`, `authMode`, `installDomain`, `other`

### CliPreviewPublishChangesCommandsAddedItems

- `command` (string, required)
- `tool` (string, required)

### CliPreviewPublishChangesCommandsChangedItems

- `command` (string, required)
- `fields` (list of enum, required)
  - Allowed values: `name`, `aliases`, `hidden`, `description`, `flags`
- `tool` (string, required)

### CliPreviewPublishChangesCommandsRemovedItems

- `command` (string, required)
- `tool` (string, required)

## Examples

**Response**

```json
{
  "binName": "string",
  "builtins": [
    {
      "command": "string",
      "description": "string"
    }
  ],
  "commands": [
    {
      "aliases": [
        "string"
      ],
      "callOnly": true,
      "command": "string",
      "example": "string",
      "flags": [
        {
          "description": "string",
          "name": "string",
          "positional": true,
          "repeatable": true,
          "required": true,
          "type": "string",
          "wire": "string",
          "default": null,
          "enum": [
            null
          ]
        }
      ],
      "help": "string",
      "hidden": true,
      "placeholderDescription": true,
      "summary": "string",
      "tool": "string",
      "usage": "string"
    }
  ],
  "displayName": "string",
  "help": "string",
  "publish": {
    "changes": {
      "commandsAdded": [
        {
          "command": "string",
          "tool": "string"
        }
      ],
      "commandsChanged": [
        {
          "command": "string",
          "fields": [
            "name"
          ],
          "tool": "string"
        }
      ],
      "commandsRemoved": [
        {
          "command": "string",
          "tool": "string"
        }
      ],
      "settings": [
        "binName"
      ]
    },
    "digest": "string",
    "publishedAt": "string",
    "publishedDigest": "string",
    "state": "unpublished",
    "version": "string"
  },
  "skill": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/products/productId/surfaces/surfaceId/cli/preview")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```