pp-xai

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/ai/xai/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# xAI — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `xai-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install xai --cli-only
   ```
2. Verify: `xai-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.4 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/ai/xai/cmd/xai-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

Use xAI's REST API from scripts and agents with JSON-first output, local cache support, and MCP tooling. The CLI keeps the official bearer-token contract and exposes read-only inspection commands for model and credential health checks.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Model planning
- **`model-picker`** — Rank live xAI models for a task using the authenticated model catalog.

  _Use this before generation, vision, embedding, image, or video workflows when an agent needs a valid model ID._

  ```bash
  xai-pp-cli model-picker --task reasoning --json --select recommendations.model,recommendations.why
  ```
- **`model-capabilities`** — Build a live capability matrix for the authenticated xAI model catalog.

  _Use this when an agent needs to choose between chat, reasoning, vision, embedding, image, and video surfaces._

  ```bash
  xai-pp-cli model-capabilities --json --select models.id,models.capabilities
  ```

### Cost and readiness
- **`cost-preview`** — Estimate xAI token cost from live model pricing metadata before sending a request.

  _Use this before a large request to estimate prompt and completion cost from xAI's current model metadata._

  ```bash
  xai-pp-cli cost-preview --task chat --input-tokens 2000 --output-tokens 500 --json
  ```
- **`smoke-chat`** — Verify that the authenticated key can run a tiny xAI chat completion.

  _Use this after auth setup to prove inference works, not only that the key is syntactically valid._

  ```bash
  xai-pp-cli smoke-chat --yes --json --select model,success,content_preview
  ```
- **`api-key`** — Inspect the authenticated xAI API key status and permissions without exposing the secret value.

  _Use this when a workflow fails with authorization errors and the agent needs a safe credential-health check._

  ```bash
  xai-pp-cli api-key --json --select api_key_blocked,api_key_disabled,acls
  ```

### Agent readiness
- **`api`** — Browse the complete generated xAI endpoint surface by interface for agent planning and fallback calls.

  _Use this when a task needs an endpoint that is not obvious from the top-level command list._

  ```bash
  xai-pp-cli api
  ```

## Command Reference

**api-key** — Manage api key

- `xai-pp-cli api-key` — Get information about an API key, including name, status, permissions and users who created or modified this key.

**chat** — Manage chat

- `xai-pp-cli chat handle-generic-completion-request` — Create a chat response from text/image chat prompts.
- `xai-pp-cli chat handle-get-deferred-completion-request` — Tries to fetch a result for a previously-started deferred completion.

**complete** — Manage complete

- `xai-pp-cli complete` — (Legacy - Not supported by reasoning models) Create a text completion response.

**completions** — Manage completions

- `xai-pp-cli completions` — (Legacy - Not supported by reasoning models) Create a text completion response for a given prompt.

**documents** — Manage documents

- `xai-pp-cli documents` — Search for content related to the query within the given collections.

**embedding-models** — Manage embedding models

- `xai-pp-cli embedding-models handle-get-request` — Get full information about an embedding model with its model_id.
- `xai-pp-cli embedding-models handle-list-request` — List all embedding models available to the authenticating API key with full information.

**embeddings** — Manage embeddings

- `xai-pp-cli embeddings` — Create an embedding vector representation corresponding to the input text.

**files** — Manage files

- `xai-pp-cli files handle-delete-request` — Delete a file by ID.
- `xai-pp-cli files handle-list-request` — List files owned by the authenticated team, paginated.
- `xai-pp-cli files handle-retrieve-request` — Retrieve metadata for a single file by ID.
- `xai-pp-cli files handle-upload-request` — Upload a file to xAI's storage. Returns the file's metadata.

**image-generation-models** — Manage image generation models

- `xai-pp-cli image-generation-models handle-get-request` — Get full information about an image generation model with its model_id.
- `xai-pp-cli image-generation-models handle-list-request` — List all image generation models available to the authenticating API key with full information.

**images** — Manage images

- `xai-pp-cli images handle-edit-request` — Edit an image based on a prompt. This is the endpoint for making edit requests to image generation models.
- `xai-pp-cli images handle-generate-request` — Generate an image based on a prompt. This is the endpoint for making generation requests to image generation models.

**language-models** — Manage language models

- `xai-pp-cli language-models handle-get-request` — Get full information about a chat or image understanding model with its model_id.
- `xai-pp-cli language-models handle-list-request` — List all chat and image understanding models available to the authenticating API key with full information.

**me** — Manage me

- `xai-pp-cli me` — Get information about the currently authenticated caller. Works with both API keys and OAuth tokens.

**messages** — Manage messages

- `xai-pp-cli messages` — Create a messages response. This endpoint is compatible with the Anthropic API.

**model-capabilities** — Build a live capability matrix for the authenticated xAI model catalog

- `xai-pp-cli model-capabilities` — List model IDs, families, input/output modalities, and inferred capabilities.

**model-picker** — Rank live xAI models for a task using the authenticated model catalog

- `xai-pp-cli model-picker` — Recommend models for chat, reasoning, vision, embedding, image, or video work.

**models** — Manage models

- `xai-pp-cli models handle-get-request` — Get information about a model with its model_id, including pricing.
- `xai-pp-cli models handle-list-request` — List all models available to the authenticating API key, including model names (ID), creation times, and pricing.

**cost-preview** — Estimate xAI token cost from live model pricing metadata

- `xai-pp-cli cost-preview` — Estimate prompt and completion cost before sending a request.

**responses** — Manage responses

- `xai-pp-cli responses handle-compact-request` — The client sends its current input (the same items that would be passed to `POST /v1/responses`)
- `xai-pp-cli responses handle-delete-stored-completion-request` — Delete a previously generated response.
- `xai-pp-cli responses handle-generic-model-request` — Generates a response based on text or image