Resource Management — Complete API Reference

The CiteKit CLI provides utilities for exploring, validating, and debugging your local resource index.

---

citekit list

Lists all resources currently stored in the .resource_maps/ directory, with optional filtering and detailed views.

Usage

# Python
python -m citekit.cli list [OPTIONS]
python -m citekit.cli list <resource_id> [OPTIONS]

# JavaScript
citekit list [OPTIONS]
citekit list <resource_id> [OPTIONS]

Options

Currently no options. Basic listing only. For JSON export of a specific resource, use citekit structure <resource_id>.

Modes

1. Global List (All Resources)

If no resource_id is provided, lists all ingested resources:

# Python
python -m citekit.cli list

# JavaScript
citekit list

Output (when resources exist):

found 3 resources:
 - lecture_01 (video): Introduction to Algorithms
 - textbook (document): Attention Is All You Need
 - codebase_v2 (text): Main Application Logic

Output (no resources):

No resources found.

Output (with corrupt/invalid resource):

found 3 resources:
 - lecture_01 (video): Introduction to Algorithms
 - mock_test (corrupt)
 - codebase_v2 (text): Main Application Logic

2. Resource Detail (Node Tree)

If a resource_id is provided, lists all nodes in that resource in hierarchical format:

# Python
python -m citekit.cli list lecture_01

# JavaScript
citekit list lecture_01

Output:

[INFO] Nodes in 'lecture_01':
- intro (section): Introduction
  - welcome (example): Welcome Message
  - objectives (list): Course Objectives
- chapter_1 (section): Chapter 1 Fundamentals
  - chapter_1.definition (definition): Definition of Algorithms
  - chapter_1.example_1 (example): Example 1
  - chapter_1.example_2 (example): Example 2
  - chapter_1.proof (explanation): Proof
  - chapter_1.exercise (problem): Practice Exercise
- chapter_2 (section): Chapter 2 Advanced Topics
  - chapter_2.intro (explanation): Introduction
  - chapter_2.algorithm (algorithm): Algorithm Description
  - chapter_2.analysis (analysis): Analysis
- conclusion (section): Conclusion
  - summary (summary): Summary

Examples

List all resources:

python -m citekit.cli list

List nodes in specific resource:

python -m citekit.cli list lecture_01

Find specific node type in resource:

python -m citekit.cli list textbook | grep "definition"

Error Codes

No resources found (Exit Code 0):

No resources found.

Invalid resource ID (Exit Code 1):

[ERROR] Resource 'nonexistent_id' not found.

---

citekit check-map

Validates a JSON map file against CiteKit's strict Pydantic models. Useful for verifying maps generated by custom adapters or manual editing.

Usage

python -m citekit.cli check-map <path/to/map.json>

Validation Checks

1. JSON Syntax: Parses and validates JSON formatting.
2. Schema Validation: Uses CiteKit's Pydantic models to validate required fields and types.
3. Sanity Check: Emits a warning if a text resource contains zero text-modality nodes.

Output Examples

Valid map:

python -m citekit.cli check-map my_map.json

Output:

[INFO] Validating my_map.json...
[SUCCESS] Map is valid.
  Schema Version: 0.1.7
   Resource ID: lecture_01
   Nodes: 12

Invalid JSON:

[INFO] Validating bad_map.json...
[ERROR] Invalid JSON syntax.

Validation error:

[INFO] Validating bad_map.json...
[ERROR] Validation Failed: field required (type=value_error.missing)

Error Codes

If the path does not exist, the CLI exits with a Click validation error before running validation.

Invalid JSON (Exit Code 1):

[ERROR] Invalid JSON syntax.

Validation failed (Exit Code 1):

[ERROR] Validation Failed: {error details}

Success (Exit Code 0):

[SUCCESS] Map is valid.

Error Codes

Invalid JSON (Exit Code 1):

[ERROR] Invalid JSON syntax.

Validation Failed (Exit Code 1):

[ERROR] Validation Failed: {error details}

---

citekit structure

Returns the raw JSON content of a resource map. Useful for piping into other tools like jq, post-processing, or debugging.

Usage

python -m citekit.cli structure <resource_id>

Output

Pure JSON output (indented 2 spaces), no prefix or labels:

python -m citekit.cli structure lecture_01

Output:

{
  "resource_id": "lecture_01",
  "type": "video",
  "title": "Introduction to Algorithms",
  "source_path": "/home/user/videos/lecture_01.mp4",
  "metadata": {
    "source_hash": "a1b2c3d4...",
    "source_size": 1024000000
  },
  "nodes": [
    {
      "id": "intro",
      "title": "Introduction",
      "type": "section",
      "location": {
        "modality": "video",
        "start": 0.0,
        "end": 145.5
      },
      "summary": "Course overview and objectives",
      "children": []
    }
  ],
  "created_at": "2025-02-16T14:32:10Z"
}

Examples

Extract node IDs with jq:

python -m citekit.cli structure lecture_01 | jq '.nodes[].id'

Output:

"intro"
"chapter_1"
"chapter_2"
"conclusion"

Get all video segments:

python -m citekit.cli structure lecture_01 | jq '.nodes[] | select(.location.modality=="video") | {id, start: .location.start, end: .location.end}'

Save to file:

python -m citekit.cli structure lecture_01 > lecture_01.json

Error Codes

Resource Not Found (Exit Code 1):

[ERROR] Resource 'nonexistent_id' not found.

Success (Exit Code 0):

{JSON output}

---

Utility: Bulk Operations

Delete a Resource

rm .resource_maps/resource_id.json

Backup All Resources

tar -czf citekit_backup.tar.gz .resource_maps/

Find Resources by Type

for file in .resource_maps/*.json; do
  grep -l '"type": "video"' "$file" | xargs -I {} basename {} .json
done

Count Total Nodes Across All Resources

for file in .resource_maps/*.json; do
  jq '.nodes | length' "$file" | awk '{sum+=$1} END {print sum}'
done

---

Data Model

interface ResourceMap {
  resource_id: string;
  type: ResourceType;  // "document" | "video" | "audio" | "image" | "text" | "virtual"
  title: string;
  source_path: string;
  metadata?: {
    source_hash: string;
    source_size: number;
    [key: string]: any;
  };
  nodes: Node[];
  created_at: string;  // ISO 8601 timestamp
}

interface Node {
  id: string;              // "chapter_1.intro"
  title?: string;
  type: string;            // "section", "example", "definition", etc.
  location: Location;
  summary?: string;
  children?: Node[];
}

interface Location {
  modality: string;        // "video" | "audio" | "document" | "image" | "text" | "virtual"
  start?: number;          // for video/audio (seconds)
  end?: number;            // for video/audio (seconds)
  pages?: number[];        // for documents (list of pages)
  lines?: [number, number];  // for text [start_line, end_line]
  bbox?: [number, number, number, number];  // for image [x1, y1, x2, y2]
  virtual_address?: string;  // for virtual nodes
}

---

Troubleshooting

Issue	Cause	Solution
"No resources found"	Empty .resource_maps/ dir	Run citekit ingest <file> first
Node tree very long	Large resource	Use citekit inspect <node_id> for specific nodes
JSON parse error	Corrupted map file	Restore from backup or re-ingest
"Invalid node ID"	Typo in dot notation	Check exact ID with citekit list <resource_id>
jq filter fails	jq not installed	Install: apt-get install jq or brew install jq