Report CLI Reference

Integrate the CLI with agents

The CLI is designed to be called by coding and workflow agents such as OpenClaw and Claude Code. It gives agents a stable command surface for files, datasources, chat sessions, and saved artifacts.

By default, responses are concise YAML and large payloads are truncated to protect an agent context window. Agents can request JSON with --json or complete output with --full when they need every field.

OpenClaw Register sr as a shell tool and ask it to use --json for machine parsing.

Claude Code Use sr from repository tasks to upload fixtures, create chats, and retrieve artifacts.

CI agents Use development e2e login or API keys to authenticate non-interactively.

Recommended agent setup

# 1. Point the CLI to your Report server
$sr config set baseUrl http://localhost:6803

# 2. Authenticate. Local dev agents can use e2e login.
$sr login --e2e

# 3. Verify credentials before running a workflow.
$sr whoami --verify

# 4. Prefer JSON when the agent needs structured parsing.
$sr --json files list

Agent guideline: Start with compact commands, request --json only when parsing is needed, and reserve --full for artifacts or exports where the complete content is strictly required.

Example Claude Code task

Use the Report CLI to upload ./data/sales.csv, wait for processing, create a chat from the uploaded file, ask for a concise trend analysis, then fetch the latest artifact. Use --json for commands whose output you need to parse.

Example OpenClaw workflow

$sr --json files upload ./inventory.csv --wait
$sr --json chat create --title "Inventory investigation" --file file_123
$sr --json chat send chat_123 "Summarize risk areas and recommend next checks"
$sr --json chat artifacts chat_123

Install and run

The CLI binary name is sr. Development uses Bun, and release builds may provide platform-specific binaries.

Mode	Command	Use when
Development	`pnpm cli:dev -- --help`	You are working from the monorepo root.
Bun source	`bun run src/index.ts --help`	You are inside `apps/cli`.
Build	`pnpm cli:build`	You want to run the compiled Bun output.
Single binary	`bun build src/index.ts --compile --outfile sr`	You want a standalone executable.
Global link	`bun link`	You want `sr` available anywhere.

# Build and run from the repository
$pnpm cli:build
$bun run apps/cli/dist/index.js --help

# Compile a standalone executable from apps/cli
$bun build src/index.ts --compile --outfile sr
$./sr --help

Configuration

The CLI reads local workspace config first, then global user config. Local config is useful for agents because each repository can point to a different Report server.

Command	Description
`sr config list`	Show effective config plus local and global config paths.
`sr config get baseUrl`	Read one config value.
`sr config set baseUrl <url>`	Set the Report server URL in local config.
`sr config set language en-US`	Set the preferred CLI language.

# Configuration Precedence
./.seeyon-report.json
~/.config/seeyon-report/seeyon-report.json

Security Warning: Do not commit real tokens or API keys. Keep .seeyon-report.json local to your machine unless it only contains safe example values.

Output modes

Default output is YAML. The default is optimized for humans and agents by omitting noisy fields and truncating very large responses.

Option	Meaning
`--json`	Print JSON instead of YAML and include full response fields.
`--verbose`	Show fuller API response fields in YAML mode.
`--full`	Disable context-safe output truncation.
`--max-output-tokens <n>`	Override the output token budget for one command.
`REPORT_CLI_MAX_OUTPUT_TOKENS`	Set the default output token budget for all commands.

$sr --json chat send chat_123 "Summarize the data"
$sr --full artifacts get artifact_123
$sr --max-output-tokens 32000 artifacts get artifact_123

Authentication

Use interactive login for normal users, e2e login for local development agents, or API keys for repeatable automation.

Command	Description
`sr login`	Prompt for email and password interactively.
`sr login --email admin@example.com`	Provide email up front, then prompt for password.
`sr login --e2e`	Dev-only login through `/e2e/login`, defaults to first admin.
`sr login --e2e --email <email>`	Dev-only login as a specific user.
`sr whoami`	Show current user information.
`sr whoami --verify`	Exit with success code only when authentication is valid.
`sr logout`	Remove the stored session token.

Files

Files are the fastest way to bring CSV, JSON, text, spreadsheet, and other supported content into Report workflows.

Command	Description
`sr files list`	List visible files in your workspace.
`sr files get <id>`	Show metadata and details for a specific file.
`sr files upload <path>`	Upload a local file.
`sr files upload <path> --wait`	Upload and wait until server-side processing finishes.
`sr files download <id> -o ./file.csv`	Download processed file data to disk.
`sr files download <id> --raw`	Print raw file data to stdout instead of saving.
`sr files update <id> --title "..."`	Update file metadata (title, notes).
`sr files delete <id>`	Permanently delete a file.
`sr files schema <id>`	Generate a JSON schema interpretation for the file.

$sr files upload ./sales.csv --title "Q4 Sales" --note "Imported by agent" --wait
$sr files schema file_123
$sr files download file_123 -o ./processed-sales.csv

Datasources

Datasources connect Report to REST APIs, SQLite files, and Quest OLAP systems. REST datasources can execute OpenAPI operations and save responses as snapshots.

Command	Description
`sr datasources list`	List visible datasources.
`sr datasources create -n API -t REST ...`	Create a REST datasource from a local OpenAPI file.
`sr datasources upload-sqlite <path>`	Upload a SQLite or DB file as a datasource.
`sr datasources rest operations <id>`	List operations from a REST datasource OpenAPI spec.
`sr datasources rest snapshot <id> ...`	Execute REST operation and save response as snapshot.
`sr datasources credentials list <id>`	List credential metadata for a datasource.
`sr datasources credentials create <id> ...`	Create an encrypted datasource credential.
`sr datasources query <id> "question"`	Ask a datasource a natural-language question.
`sr datasources sql <id> "query"`	Execute raw SQL against a datasource.
`sr datasources delete <id>`	Delete a datasource.

# REST datasource from OpenAPI
$sr datasources create -n "DummyJSON" -t REST --openapi-file ./openapi.yaml
$sr datasources rest snapshot ds_123 --operation-id listProducts --query '{"limit":2}'

# SQLite datasource
$sr datasources upload-sqlite ./warehouse.db -n "Warehouse DB" --public

Quest Note: OLAP datasource creation is Quest-only. Enable with SEEYON_REPORT_CLI_BUILD_PLAN=QUEST.

Chat

Chat commands let agents and users create analysis workspaces, attach context, send non-streaming prompts, and request standard analysis report types.

Command	Description
`sr chat list`	List recent chats.
`sr chat get <id>`	Get chat details and message history.
`sr chat create --file <id>`	Create a chat with attached files.
`sr chat create --datasource <id>`	Create a chat with datasource and snapshot context.
`sr chat send <id> "message"`	Send a non-streaming message to the assistant.
`sr chat analyze <id> <type>`	Generate diagnostic, predictive, or prescriptive reports.
`sr chat artifacts <id>`	List artifacts generated within a specific chat.

$sr chat create --title "Revenue review" --file file_123 --datasource ds_456
$sr chat send chat_123 "What changed most significantly this month?"
$sr chat analyze chat_123 diagnostic --context "Focus on customer segment changes"

Artifacts & Reports

Artifacts are saved outputs from chats (tables, charts, code). Reports track async generation workflows.

Command	Description
`sr artifacts list`	List saved artifacts across all sessions.
`sr artifacts get <id>`	Get detailed content of one saved artifact.
`sr generate <pod-id>`	Generate a report for a pod (Quest-only).
`sr status <task-id>`	Check asynchronous report generation status.
`sr export <report-id> --format pdf`	Export a saved report locally to a file.

Pods and skills

Pods and skills are Quest features for advanced agent workspaces. They are hidden unless the CLI build plan enables them via environment variables.

$SEEYON_REPORT_CLI_BUILD_PLAN=QUEST sr --help

Command	Description
`sr pods create -n "Ops" --files f1`	Create a pod with linked Report files.
`sr pods launch <id>`	Open the pod workspace in a web browser.
`sr skills create --dir ./my-skill`	Create a skill from a directory containing `SKILL.md`.
`sr skills update <id> --dir ./skill`	Sync updates from a local skill directory.

Agent recipes

Common invocation patterns for automation scripts and AI agents.

Upload, analyze, retrieve artifact

$sr --json files upload ./sales.csv --wait
$sr --json chat create --title "Sales analysis" --file file_123
$sr --json chat analyze chat_123 descriptive
$sr --full artifacts get artifact_123

Safe preflight for CI automation

$sr config get baseUrl
$sr whoami --verify
$sr files list

Report from the terminal

Integrate the CLI with agents

Recommended agent setup

Example Claude Code task

Example OpenClaw workflow

Install and run

Configuration

Output modes

Authentication

Files

Datasources

Chat

Artifacts & Reports

Pods and skills

Agent recipes

Upload, analyze, retrieve artifact

Safe preflight for CI automation