Skip to main content

​
Agent Operating Guide

This guide is for AI agents working with the casedev CLI. It covers CLI discovery, vault workflows, matter analysis, and common pitfalls — distilled from real agent failures in production.
This document is designed to be embedded directly into agent system prompts or instruction files.

​
CLI Discovery

The casedev CLI does not follow a single naming convention. Commands, subcommands, and flags vary across command families. Always inspect help before running a command you haven’t used before. 
# Discovery order
casedev --help                          # top-level commands
casedev <group> --help                  # subcommands in a group
casedev <group> <subcommand> --help     # flags for a specific command
Rules:
  • Do not assume flag names transfer between command families (e.g. --id vs --object-id vs --vault-id)
  • Do not assume REST endpoint names map to CLI subcommands
  • If two attempts fail because the command shape is wrong, stop guessing — re-read --help and try a different approach

​
Vault Workflows

​
List vaults

casedev vault list --format json

​
List objects in a vault

casedev vault:objects list --id <vault_id> --format json

​
Upload a file

Three-step process: create upload session → PUT the file → confirm. 
# 1. Create upload session
casedev vault upload --id <vault_id> \
  --filename "brief.pdf" \
  --content-type "application/pdf" \
  --size-bytes 42000 \
  --auto-index \
  --format json

# 2. PUT the file to the returned uploadUrl (use curl or equivalent)

# 3. Confirm
casedev vault confirm-upload --id <vault_id> \
  --object-id <object_id> \
  --success \
  --size-bytes 42000 \
  --error-code "" \
  --error-message ""
The confirm step requires --error-code "" and --error-message "" even on success. Do not assume a vault:objects upload shortcut exists — use the three-step flow above.

​
Get extracted text

casedev vault:objects get-text --id <vault_id> --object-id <object_id> --format json
Only call this after you’ve identified the specific document you need.

​
GraphRAG

Do not assume GraphRAG supports free-form querying. Always inspect the available subcommands first: 
casedev vault:graphrag --help
Known subcommands include get-stats, init, and process-object — but the surface may change.

​
Matter Analysis Workflow

When analyzing a matter (a legal case with uploaded documents), work in this order:

​
1. Build a filing map

List the vault objects and identify anchor documents first:
  • Complaint / amended complaint
  • Answer
  • Motion to dismiss + opposition + reply
  • Court orders
  • Key declarations
Ignore peripheral filings until you’ve covered the core.

​
2. Extract parties

Start with the civil cover sheet, complaint caption, or answer caption — these are the most reliable sources.

​
3. Read the complaint

Focus on:
  • Opening factual overview
  • Causes of action
  • Prayer for relief
Do not start from an arbitrary middle section.

​
4. Read defense arguments

Prioritize the latest operative defense briefs:
  • Motion to dismiss
  • Answer / affirmative defenses
  • Brief headings and issue statements

​
5. Compile evidence

Tie evidence to actual filings — emails, contracts, declarations, exhibits cited in briefs.

​
6. Write the summary

Structure:
  1. Parties
  2. Claims
  3. Key evidence
  4. Plaintiff arguments
  5. Defense arguments
  6. Procedural posture
  7. Open uncertainties

​
Document Prioritization

PriorityDocument types
HighComplaint, amended complaint, answer, motion to dismiss, opposition/reply, court orders
MediumDeclarations supporting core motions, key exhibits cited in briefs, case management orders
LowStray exhibits, side motions by non-core parties, intervention attempts, uncited appendices

​
Reading Best Practices

  • Use filenames as hints — 001-Complaint.pdf tells you more than a text search
  • Read small, targeted sections first — issue statements, prayer for relief, conclusion sections
  • Don’t dump entire documents hoping to find the answer
  • Watch for OCR noise — corroborate with other filings if text quality is poor, rely on headings over garbled body text
  • Never claim full understanding from partial text — if content is truncated or starts mid-document, say so and keep collecting

​
Anti-Patterns

CategoryWhat to avoid
CLIGuessing subcommands from API names, repeating wrong flags, skipping --help, treating help output as a success response
AnalysisStarting with peripheral filings, summarizing from truncated excerpts, conflating allegations with proven facts, overstating confidence

​
Prompt Snippet

Embed this in agent instructions for reliable casedev usage: 
Never guess casedev commands — inspect --help first. For matter analysis,
identify anchor filings before reading text. Prefer targeted retrieval over
raw document dumps. Do not claim comprehensive understanding from truncated
or mid-document excerpts. After two command-shape failures, stop and remap
the CLI surface.