stqry

CLI for managing collections, screens, media, and content on STQRY.

Installation

Homebrew

brew install mytours/tap/stqry-cli

Go Install

go install github.com/mytours/stqry-cli/cmd/stqry@latest

GitHub Releases

Download the latest binary for your platform from GitHub Releases.

Quick Start

Configure the current directory with your STQRY API key (writes stqry.yaml):

stqry config init --api-key=<API_KEY> --region=us

List collections:

stqry collections list

Create a screen (--type is required, plus --name OR --title; --type must be one of story, web, panorama, ar, kiosk):

stqry screens create --name="Welcome" --type=story

Create a media item from a local file (uploads the file and creates a media item linked to it). --type must be one of map, webpackage, animation, audio, image, video, webvideo, ar, data. For audio and video the CLI falls back to --title when --name is omitted; every other type needs --name explicitly:

stqry media create --file=./photo.jpg --type=image --name=photo.jpg

AI Agent Integration

The CLI ships two pieces of context for Claude: a command reference (stqry skill cat reference) and step-by-step workflow recipes (stqry skill cat workflows). Both print the latest documentation embedded in the installed binary — no separate install step.

Claude Code — two options, pick one (they don't conflict):

• Per-project: run stqry config init in the project directory. It writes a CLAUDE.md that points Claude at stqry skill cat reference / workflows, so Claude pulls live content on demand whenever you work in that project.
• Globally: run stqry setup claude once. It installs the same skill content at ~/.claude/skills/stqry/SKILL.md, so Claude Code auto-loads it whenever you mention STQRY content from any directory.

Claude Desktop — export a skill zip and install via the UI:

stqry skill export          # writes ./stqry-skill.zip

Then open Claude Desktop → Settings → Customise → Skills → Add Skill, select stqry-skill.zip, and restart. The zip is timeless — its SKILL.md calls stqry skill cat at runtime, so a single upload stays valid across CLI releases.

Alternatively, download stqry-skill.zip directly from the latest GitHub release — no CLI install needed.

Claude Cowork — install via pip and use as CLI subprocess:

pip install stqry
stqry --version   # verify

MCP server setup is not required in Claude Cowork — use the CLI as a subprocess.

To inspect skill content directly:

stqry skill cat reference       # full command reference
stqry skill cat workflows       # multi-step recipes
stqry skill export --dir /tmp   # write Claude Desktop zip to /tmp/stqry-skill.zip

MCP Server

stqry mcp serve starts an MCP server over stdio, letting AI assistants read and manage STQRY content directly.

Claude Code — add to .claude/settings.json in your project:

{
  "mcpServers": {
    "stqry": {
      "command": "stqry",
      "args": ["mcp", "serve"]
    }
  }
}

The server picks up stqry.yaml from the project directory automatically.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "stqry": {
      "command": "stqry",
      "args": ["mcp", "serve"]
    }
  }
}

No account is hardcoded. At the start of each conversation, tell Claude which project to connect to:

• "My API key is abc123, region is US" — Claude will configure it for you (writes stqry.yaml).

Output Formats

Commands support multiple output formats:

Default (human-readable):

stqry collections list

JSON output — wraps results in a { "data": [...], "meta": {...} } envelope:

stqry collections list --json

Quiet mode — emits only the raw data payload (no envelope), handy for piping:

stqry collections list --quiet

Built-in --jq — filter results without piping to an external jq binary. Always runs against the bare data (the array of rows), so the same expression works with or without --json. Pair with --raw / -r to emit string outputs as raw text instead of JSON-quoted strings (mirrors jq -r):

stqry collections list --jq '.[].name'
stqry collections get 42 --jq '.title.en' -r       # → plain string, no quotes
stqry media list --jq '[.[] | select(.file_size > 500000)]'

External jq is still useful when you need the meta envelope (the built-in --jq strips it):

stqry collections list --json | jq '.meta.pages'

Pagination

Every list command paginates server-side. The default is 30 rows per page; max is 1000 (server-enforced — --per-page > 1000 returns HTTP 400). When you don't pass --per-page you only see the first 30 rows — silent truncation has historically been the worst foot-gun for scripted enumeration.

Signals that more pages exist:

• Human mode — footer like Showing 30 of 1017 (page 1 of 34) — pass --page / --per-page to see more.
• --json mode — the envelope's meta field: {"page": 1, "per_page": 30, "pages": 34, "count": 1017}.
• --quiet / --jq mode — the envelope is stripped from stdout, but a warning: showing N of TOTAL results … line is mirrored to stderr so it's still visible to humans and grep-able from scripts.

When you need every row, either bump --per-page to 1000 (one call covers most accounts) or walk pages until you reach meta.pages.

Account Configuration

STQRY CLI stores credentials in a per-project stqry.yaml file. Create one with:

stqry config init --api-key=<API_KEY> --region=us

This writes:

api_key: <API_KEY>
api_url: https://api-us.stqry.com

The CLI walks up the directory tree, so a stqry.yaml in a project root applies to all subdirectories.

Legacy global config

A historical ~/.config/stqry/config.yaml file may still exist with named accounts in the old format. It is read-only going forward: when a project's stqry.yaml references one of those named accounts, the credentials are automatically inlined on the next command and global config is no longer consulted for that project.

If no account is configured, the command will return an error prompting you to run stqry config init.