---
name: xpod-cli
description: Use when designing, implementing, reviewing, testing, or using the Xpod CLI; especially docs/cli-spec.md, raw Pod resource commands, server commands, auth and JSON output contracts, RDF/obj/secret boundaries, marketplace plugin metadata, and release/install validation.
---

# Xpod CLI

Use this skill when work touches the `xpod` command line, its canonical spec,
or agent-facing workflows that depend on the CLI.

## First Checks

- If working inside the xpod repository, read `docs/cli-spec.md` before making
  command-surface decisions.
- If the task touches durable RDF/model semantics, also use the Solid Modeling
  guidance from the `solid-modeling` plugin.
- Prefer the repository's existing TypeScript/yargs command-module patterns and
  Bun scripts.

## Command Boundaries

- Top-level `get`, `put`, `patch`, `delete`, `head`, and `list` are raw Pod
  resource operations only. They must not infer object schemas, business
  models, or product-specific paths.
- Use `xpod server ...` for process/runtime administration:
  `start`, `stop`, `status`, `health`, `logs`, and `config`.
- Do not introduce `xpod run`; foreground startup is
  `xpod server start --foreground`.
- Do not introduce `xpod curl`; the CLI can be curl-like without accepting curl
  compatibility flags.
- Top-level `xpod config` must not mean Pod, AI, or model configuration. If it
  exists temporarily, it may only alias `xpod server config`.
- Use `xpod rdf ...` for graph/resource/subject/triple operations.
- Use `xpod obj ...` for model-backed object transport. Its catalog must be
  exported or derived from `@undefineds.co/models`; xpod must not maintain a
  product descriptor table or invent fallback schemas.
- `xpod obj` must delegate storage resolution, id/default behavior,
  validation, writable fields, secret markers, and filterable fields to
  `@undefineds.co/models`. If an explicit base-relative `id` is present, treat
  it as exact.
- `obj list`, `obj get`, and `obj export` must discover readable resources
  through the model catalog/resource API first. Profile registration is not the
  only discovery source: exact ids, canonical model storage, resource indexes,
  and enumerable storage roots may all be models-owned read paths. For Data
  Interop, ShapeTree, or TypeRegistration-backed models, use the registration
  path only when the model declares it; return `storage_unresolved` instead of
  falling back to a full-Pod RDF class scan.
- Use `xpod secret ...` only for secret-safe plans, writes, metadata, and
  revocation. Never print secret values by default.

## Output And Auth

- JSON output uses `{ ok, code, data, warnings }` for success and
  `{ ok: false, code, message, warnings }` for errors.
- Batch output includes per-item `index`, `ok`, and machine-readable `code`.
- In `--json`, CI, or non-interactive mode, missing auth must return
  `code: "auth_required"` and must not open a browser.
- Never print access tokens, refresh tokens, client secrets, cookies, or
  authorization headers unless a human-only debug flag explicitly asks for it.
- Commands that depend on Pod context should report effective WebID, Pod root,
  base IRI, and resource URL in JSON output.

## Implementation Checklist

- Register command modules in `src/cli/index.ts` and keep root help from
  swallowing subcommand help.
- Keep raw resource helpers separate from RDF/model/secret helpers.
- Validate model-backed object work through `@undefineds.co/models` catalog or
  resource APIs; report `schema_unknown` or `storage_unresolved` instead of
  deriving paths or schemas inside xpod.
- Preserve input order in `obj import` batch results and return per-item
  `index`, `ok`, `code`, and resource metadata when available.
- Use `drizzle-solid` or shared model APIs for business resources when code is
  in-process. Keep xpod CLI as the external human/script/agent tool surface.
- Update tests with the command-surface change. Existing AI-specific
  `config` tests should not keep the old top-level meaning alive.

## Verification

- Run `bun run build:ts` after TypeScript CLI changes.
- Run focused CLI tests for changed commands and helpers.
- Before claiming completion of substantive implementation work, run
  `bun run test:integration` or report the concrete blocker.
- For marketplace/plugin work, validate `plugins/xpod-cli` with the Codex
  plugin validator and parse both marketplace JSON files.