# Castorini Cli Reference

> Use when building, debugging, or reviewing CLI commands across nuggetizer, ragnarok, rank_llm, or umbrela and you need the shared castorini.cli.v1 envelope, common introspection commands, artifact shapes, or cross-repo CLI consistency rules.

- **Type:** Skill
- **Install:** `agentstack add skill-castorini-castorini-skills-castorini-cli-reference`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [castorini](https://agentstack.voostack.com/s/castorini)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [castorini](https://github.com/castorini)
- **Source:** https://github.com/castorini/castorini-skills/tree/main/skills/castorini-cli-reference

## Install

```sh
agentstack add skill-castorini-castorini-skills-castorini-cli-reference
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Castorini CLI Reference

Quick reference for the shared CLI contract across the four Python Castorini repos: **nuggetizer**, **ragnarok**, **rank_llm**, and **umbrela**.

All four repos expose a repo-named binary (`nuggetizer`, `ragnarok`, `rank-llm`, `umbrela`) with converged introspection commands and the `castorini.cli.v1` JSON envelope.

The flag matrix is closest across `nuggetizer`, `ragnarok`, and `umbrela`. `rank_llm` shares the introspection surface and envelope shape, but some execution flags and artifact naming are repo-specific.

When a task depends on the current contract shape, start with ` describe ...`, ` schema ...`, or ` doctor --output json` before assuming a sibling repo matches remembered behavior.

## Shared Command Families

Every repo exposes:

| Command | Purpose |
|---------|---------|
| `describe ` | Machine-readable contract: flags, defaults, enums, examples |
| `schema ` | JSON Schema for inputs, outputs, envelope |
| `doctor` | Environment and dependency preflight |
| `validate ` | Input/artifact validation without model execution |
| `prompt list\|show\|render` | Inspect and render prompt templates |
| `view ` | Inspect existing artifact files |

Plus repo-specific execution verbs:
- **nuggetizer**: `create`, `assign`, `metrics`
- **ragnarok**: `generate`, `validate`, `convert`
- **rank_llm**: `rerank`, `evaluate`, `analyze`, `retrieve-cache`, `serve`
- **umbrela**: `judge`, `evaluate`

## Reference Files

Read these on demand for detailed specifications:

- `references/envelope-schema.md` — Full `castorini.cli.v1` envelope specification
- `references/shared-flags.md` — Common flags and introspection commands across the shared Castorini CLIs
- `references/artifact-shape.md` — Artifact metadata shape and conventions

## Gotchas

- **Flag casing**: All four repos use kebab-case for packaged CLI flags (`--input-file`, not `--input_file`). Legacy compatibility scripts may still use snake_case internally.
- **`--output` vs `--output-file`**: `--output` controls format (`text|json|jsonl`); `--output-file` controls destination path. These are independent.
- **Write policies are mutually exclusive**: `--resume`, `--overwrite`, and `--fail-if-exists` cannot be combined.
- **`--dry-run` vs `--validate-only`**: `--dry-run` resolves inputs and reports what would happen. `--validate-only` checks the declared contract (schemas, types) without resolving resources.
- **Exit code 7** means partial success — some records succeeded, others failed. Check `errors` array in the JSON envelope.
- **`rank_llm` command names differ**: its primary execution verbs are `rerank` and `evaluate`, not `generate` or `judge`.
- **No automated contract tests** yet verify sibling CLIs agree on the shared envelope. When in doubt, inspect the target repo directly with ` schema ` or ` describe `.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [castorini](https://github.com/castorini)
- **Source:** [castorini/castorini-skills](https://github.com/castorini/castorini-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-castorini-castorini-skills-castorini-cli-reference
- Seller: https://agentstack.voostack.com/s/castorini
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.