Agent Operating Guide

How to use the case.dev CLI and APIs reliably as an agent

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.

Shell

# 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

Shell

casedev vault list --format json

List objects in a vault

Shell

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

Upload a file

Three-step process: create upload session → PUT the file → confirm.

Shell

# 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

Shell

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:

Shell

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

Priority	Document types
High	Complaint, amended complaint, answer, motion to dismiss, opposition/reply, court orders
Medium	Declarations supporting core motions, key exhibits cited in briefs, case management orders
Low	Stray 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

Category	What to avoid
CLI	Guessing subcommands from API names, repeating wrong flags, skipping --help, treating help output as a success response
Analysis	Starting 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.