COSMIC Command Line Interface¶

Complete reference for the cosmic CLI tool.

Commands Overview¶

Command	Description
`cosmic chunk`	Chunk a document using COSMIC pipeline
`cosmic ollama`	Manage Ollama integration
`cosmic version`	Display version information
`cosmic benchmark`	Run benchmark suite

cosmic chunk¶

Chunk a document using the COSMIC pipeline.

Synopsis¶

cosmic chunk FILE [OPTIONS]

Arguments¶

Argument	Description
`FILE`	Path to the input file to chunk

Options¶

Option	Short	Default	Description
`--strategy`	`-s`	`auto`	Chunking strategy
`--output`	`-o`	stdout	Output JSON file
`--config`	`-c`	-	Configuration YAML file
`--no-llm`	-	-	Disable LLM verification
`--no-reference`	-	-	Disable reference linking
`--ollama`	-	-	Use Ollama for LLM verification
`--verbose`	`-v`	-	Enable verbose logging

Strategy Values¶

Strategy	Description
`auto`	Automatically select based on document structure
`full`	Full 6-stage COSMIC pipeline
`semantic`	Semantic boundaries only (DCS-based)
`sliding`	Sliding window with basic similarity
`fixed`	Fixed-length token splitting

Examples¶

Basic Usage¶

# Chunk with automatic strategy selection
cosmic chunk document.txt

# Chunk a markdown file
cosmic chunk README.md

# Chunk with verbose output
cosmic chunk document.txt -v

Strategy Selection¶

# Full 6-stage pipeline (highest quality)
cosmic chunk document.txt --strategy full

# Semantic-only (faster, good quality)
cosmic chunk document.txt --strategy semantic

# Sliding window (fast, basic quality)
cosmic chunk document.txt --strategy sliding

# Fixed-length (fastest, baseline quality)
cosmic chunk document.txt --strategy fixed

# Short form
cosmic chunk document.txt -s full

Output Options¶

# Save to JSON file
cosmic chunk document.txt --output chunks.json
cosmic chunk document.txt -o chunks.json

# Save with specific strategy
cosmic chunk document.txt -s full -o output/chunks.json

# Pretty-print to terminal (default)
cosmic chunk document.txt

Configuration¶

# Use custom configuration file
cosmic chunk document.txt --config configs/custom.yaml
cosmic chunk document.txt -c configs/custom.yaml

# Combine config with strategy override
cosmic chunk document.txt -c configs/custom.yaml -s semantic

Disabling Pipeline Stages¶

# Disable LLM verification (Stage 5)
cosmic chunk document.txt --strategy full --no-llm

# Disable reference linking (Stage 6)
cosmic chunk document.txt --strategy full --no-reference

# Disable both
cosmic chunk document.txt --strategy full --no-llm --no-reference

Ollama Integration¶

# Auto-detect and use best available model
cosmic chunk document.txt --strategy full --ollama

# Equivalent to above (explicit auto)
cosmic chunk document.txt --strategy full --ollama auto

# Use specific model
cosmic chunk document.txt --strategy full --ollama gemma3:latest
cosmic chunk document.txt --strategy full --ollama qwen2.5-coder:7b

# Combine with output
cosmic chunk document.txt -s full --ollama gemma3 -o chunks.json

Output Format¶

When no --output is specified, results are printed to stdout:

Document: README
Strategy: auto
Chunks: 75

--- Chunk 0 ---
  Tokens: 45
  Coherence: 1.000
  Domain: technical
  Mode: FULL_COSMIC
  Preview: # COSMIC: COncept-aware Semantic Meta-chunking with Intelligent Classification...

--- Chunk 1 ---
  Tokens: 20
  Coherence: 1.000
  Domain: technical
  Mode: FULL_COSMIC
  Preview: ## Research Objectives COSMIC addresses fundamental limitations...

When --output is specified, a JSON file is created:

{
  "document_id": "README",
  "source_file": "README.md",
  "strategy": "auto",
  "num_chunks": 75,
  "chunks": [
    {
      "chunk_id": "abc123def456",
      "document_id": "README",
      "chunk_index": 0,
      "text": "...",
      "token_count": 45,
      "location": { ... },
      "domain": { ... },
      "quality": { ... },
      "references": { ... },
      "intent": { ... },
      "structure": { ... },
      "provenance": { ... }
    }
  ]
}

cosmic ollama¶

Manage Ollama integration for LLM verification.

Synopsis¶

cosmic ollama [ACTION]

Actions¶

Action	Description
`status`	Show Ollama installation and server status (default)
`list`	List available Ollama models
`start`	Start the Ollama server
`stop`	Show how to stop the Ollama server

Examples¶

Check Status¶

# Show Ollama status (default action)
cosmic ollama
cosmic ollama status

Output:

Ollama Status:
  Installed: Yes
  Running: Yes
  Models available: 6
  Recommended model: gemma3:latest

List Models¶

cosmic ollama list

Output:

Available Ollama models:
NAME                                     SIZE
--------------------------------------------------
qwen3:30b-a3b                            18.0 GB
qwen2.5-coder:7b                         4.7 GB
deepseek-coder-v2:latest                 8.9 GB
llama4:latest                            67.0 GB
gemma3:latest                            3.3 GB

Recommended for COSMIC: gemma3:latest

Start Server¶

cosmic ollama start

Output:

Ollama server started

Stop Server¶

cosmic ollama stop

Output:

Note: Use 'ollama stop' or 'pkill ollama' to stop the server

cosmic version¶

Display COSMIC version information.

Synopsis¶

cosmic version

Example¶

cosmic version

Output:

COSMIC v1.0.0
COncept-aware Semantic Meta-chunking with Intelligent Classification

cosmic benchmark¶

Run the COSMIC benchmark suite.

Synopsis¶

cosmic benchmark [OPTIONS]

Options¶

Option	Short	Description
`--documents`	`-d`	Directory containing documents to benchmark

Examples¶

# Quick sanity check
cosmic benchmark

# Benchmark with custom documents
cosmic benchmark --documents ./test_documents/
cosmic benchmark -d ./test_documents/

Output:

Running COSMIC benchmark...
(Use benchmarks/run_validation.py for full benchmark)
Quick test: 1 chunks created

For comprehensive benchmarking, use the Python runner directly:

# Full benchmark suite
python -m benchmarks.runner

# Specific datasets
python -m benchmarks.runner --datasets arxiv pubmed

# Limited samples
python -m benchmarks.runner --limit 100

Global Options¶

These options apply to all commands:

Option	Short	Description
`--verbose`	`-v`	Enable verbose/debug logging
`--help`	`-h`	Show help message

Examples¶

# Show main help
cosmic --help
cosmic -h

# Show command-specific help
cosmic chunk --help
cosmic ollama --help

# Enable verbose logging
cosmic -v chunk document.txt
cosmic chunk document.txt -v

Environment Variables¶

The CLI respects these environment variables:

Variable	Default	Description
`COSMIC_LLM_PROVIDER`	`openai`	LLM provider: openai, ollama, auto
`COSMIC_LLM_URL`	`http://localhost:8000/v1`	LLM API endpoint
`COSMIC_LLM_MODEL`	`default`	LLM model name
`COSMIC_LLM_API_KEY`	-	API key for LLM
`OLLAMA_HOST`	`http://localhost:11434`	Ollama server URL
`COSMIC_OLLAMA_MODEL`	`auto`	Ollama model to use
`COSMIC_EMBEDDING_DEVICE`	`cuda`	Device for embeddings

Examples¶

# Use CPU for embeddings
COSMIC_EMBEDDING_DEVICE=cpu cosmic chunk document.txt

# Use specific Ollama model by default
COSMIC_OLLAMA_MODEL=gemma3:latest cosmic chunk document.txt --ollama

# Configure LLM endpoint
COSMIC_LLM_URL=http://my-llm-server:8000/v1 cosmic chunk document.txt

Exit Codes¶

Code	Description
`0`	Success
`1`	Error (file not found, invalid options, etc.)

Common Workflows¶

Quick Document Chunking¶

# Simple chunking with sensible defaults
cosmic chunk my_document.txt

High-Quality Chunking with Local LLM¶

# Use full pipeline with Ollama verification
cosmic chunk document.txt --strategy full --ollama auto

Fast Processing¶

# Skip expensive stages for speed
cosmic chunk document.txt --strategy semantic --no-reference

Batch Processing via Shell¶

# Process multiple files
for f in documents/*.txt; do
  cosmic chunk "$f" -o "output/$(basename "$f" .txt).json"
done

# Parallel processing with xargs
ls documents/*.txt | xargs -P4 -I{} cosmic chunk {} -o output/{}.json

CI/CD Integration¶

# Consistent, reproducible chunking
cosmic chunk document.txt \
  --config configs/production.yaml \
  --strategy full \
  --no-llm \
  --output chunks.json

Development/Testing¶

# Quick iteration with verbose output
cosmic -v chunk test.txt --strategy semantic

# Benchmark after changes
cosmic benchmark

Troubleshooting¶

File Not Found¶

Error: File not found: document.txt

Solution: Verify the file path exists and is readable.

Ollama Not Installed¶

Error: Ollama is not installed
Install from: https://ollama.com/download

Solution: Install Ollama from the official website.

No Ollama Models¶

Error: No Ollama models available
Pull a model with: ollama pull gemma3

Solution: Pull a model using ollama pull <model>.

LLM Connection Failed¶

[COSMIC_E003] Failed to connect to LLM endpoint

Solutions: 1. Use --no-llm to disable LLM verification 2. Use --ollama for local LLM 3. Configure a valid endpoint in .env

Memory Issues¶

Solutions: 1. Use COSMIC_EMBEDDING_DEVICE=cpu 2. Use --strategy semantic or --strategy fixed 3. Process smaller documents

COSMIC Command Line Interface¶

Commands Overview¶

cosmic chunk¶

Synopsis¶

Arguments¶

Options¶

Strategy Values¶

Examples¶

Basic Usage¶

Strategy Selection¶

Output Options¶

Configuration¶

Disabling Pipeline Stages¶

Ollama Integration¶

Output Format¶

cosmic ollama¶

Synopsis¶

Actions¶

Examples¶

Check Status¶

List Models¶

Start Server¶

Stop Server¶

cosmic version¶

Synopsis¶

Example¶

cosmic benchmark¶

Synopsis¶

Options¶

Examples¶

Global Options¶

Examples¶

Environment Variables¶

Examples¶

Exit Codes¶

Common Workflows¶

Quick Document Chunking¶

High-Quality Chunking with Local LLM¶

Fast Processing¶

Batch Processing via Shell¶

CI/CD Integration¶

Development/Testing¶

Troubleshooting¶

File Not Found¶

Ollama Not Installed¶

No Ollama Models¶

LLM Connection Failed¶

Memory Issues¶

See Also¶