CLI Reference v1.0.0

Identity Preserving Publishing Engine generate articles and series in your authentic voice using AI.

Installation

Prerequisites: Node.js 22+ and a C++ compiler (required by better-sqlite3 and sqlite-vec native modules). On macOS, Xcode Command Line Tools (xcode-select --install) is sufficient.

npm install -g @serticode/thoth

Or run without installing:

npx @serticode/thoth init

AI Provider Setup (optional)

Set at least one API key environment variable to use cloud AI. Add these to your shell profile (~/.zshrc or ~/.bashrc) so they persist across sessions. If no keys are set, Thoth falls back to local Ollama.

export OPENAI_API_KEY=sk-...     // OpenAI 
export ANTHROPIC_API_KEY=sk-...  // Anthropic Claude
export GEMINI_API_KEY=...        // Gemini (free tier available)
export GROQ_API_KEY=...          // Groq (fast inference)

To run entirely offline with no API keys, install Ollama and pass --local:

thoth --local init

Global Options

Global options apply to every command. --local and --provider can also be set in thoth.json or environment variables.

Configuration

Thoth reads config from two locations (merged in order, later wins):

1. Project config ./thoth.json (current working directory)
2. User config ~/.thoth/thoth.json (home directory)

Schema

{
  "provider": "openai",        // Default AI provider
  "chatModel": "gpt-4o-mini",  // Override chat model
  "embeddingModel": "text-embedding-3-small", // Override embedding model
  "local": false,              // Force local only mode
  "dbPath": "/path/to/custom.db", // Custom database location
  "logLevel": "error",         // Logging level (error, warn, info, debug)
  "export": {
    "format": "md",            // Default export format
    "outputDir": "./out"       // Default export directory
  }
}

Environment Variables

Config Merge Priority

CLI flag > Environment variable > Config file > Default

AI Providers

Thoth supports five AI providers. Each has its own API key env var and default model. Providers are tried in priority order; if one fails, the next is attempted (3 retries with exponential backoff per provider).

Provider Chain

Providers are tried in quality priority order. Each gets 3 retries with exponential backoff before falling through to the next. Ollama is always last as the local fallback.

OpenAI → Groq → Gemini → Anthropic → Ollama
	  (tried in order; Ollama is the always-available last resort)

Provider Reference

Custom Models

Override any provider's default model:

THOTH_CHAT_MODEL=gpt-4o thoth generate_article --topic "My Topic"
THOTH_EMBEDDING_MODEL=text-embedding-ada-002 thoth import_knowledge ./docs

Ollama Configuration

OLLAMA_BASE_URL=http://localhost:11434/v1  // default
OLLAMA_CHAT_MODEL=qwen2.5:7b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

Privacy

Pass --local (or set THOTH_LOCAL=true or "local": true in config) to restrict Thoth to Ollama only. No source content leaves your machine.

Commands

thoth init [options]

thoth import_voice <path>

thoth import_knowledge <path>

thoth import_publications <path>

thoth generate_profile [options]

thoth profile_status [options]

thoth research <topic>

thoth generate_article --topic <topic> [--research <id>]
thoth generate_article --research <id>

thoth list_articles [options]

thoth get_article <id>

thoth create_series <name> [--description <text>]

thoth list_series [options]

thoth add_to_series <series-id> <article-id>

thoth get_series <id>

thoth export_article <id> [--format <format>] [--output <dir>] [--stdout]

thoth export_series <id> [--format <format>] [--output <dir>]

End to End Workflow

 1. Initialize           thoth init
 2. Import voice         thoth import_voice ./journals/
 3. Import knowledge     thoth import_knowledge ./notes/
 4. Import publications  thoth import_publications ./articles/
 5. Generate profiles    thoth generate_profile
 6. Check status         thoth profile_status
 7. Research a topic     thoth research "Distributed Systems Design"
 8. Write article        thoth generate_article --topic "..." --research rn_abc123
 9. Create series        thoth create_series "Distributed Systems"
10. Add to series        thoth add_to_series ser_abc123 art_def456
11. Export article       thoth export_article art_def456 --format html
12. Export series        thoth export_series ser_abc123 --format rss

Minimal Workflow (local only, no API keys)

thoth init
thoth import_voice ./my-writing/
thoth generate_profile
thoth generate_article --topic "My First Post"
thoth export_article art_xxx --format html --output ./out

Domain Entity Reference

SourceReference

interface SourceReference {
  id: string;         // unique ID
  type: "voice" | "knowledge" | "publication";
  sourcePath: string; // original file path
  content: string;    // chunked text content
  checksum: string;   // content hash (dedup)
  chunkIndex: number; // position within source file
  createdAt: Date;
}

VoiceProfile

interface VoiceProfile {
  id: string;
  name: string | null;
  traits: {
    tone: string[];
    pacing: string[];
    storytelling: string[];
    vocabulary: string[];
    sentenceStructure: string[];
    transitions: string[];
    humor: string[];
    readerEngagement: string[];
  };
  summary: string | null;
  createdAt: Date;
}

KnowledgeProfile

interface KnowledgeProfile {
  id: string;
  domains: string[];
  topics: string[];
  summary: string | null;
  createdAt: Date;
}

PublicationProfile

interface PublicationProfile {
  id: string;
  themes: string[];
  series: { name: string; articles: ArticleReference[] }[] | null;
  summary: string | null;
  createdAt: Date;
}

ResearchNote

interface ResearchNote {
  id: string;
  topic: string;
  content: string;
  citations: {
    sourceId: string;
    sourcePath: string;
    excerpt: string;
    relevanceScore: number;
  }[];
  createdAt: Date;
}

Article

interface Article {
  id: string;
  title: string;
  content: string;       // markdown body
  voiceProfileId: string; // which voice was used
  researchId: string | null;
  wordCount: number;
  status: "draft" | "published" | "archived";
  createdAt: Date;
  updatedAt: Date;
}

Series

interface Series {
  id: string;
  name: string;
  description: string | null;
  articleIds: string[];   // ordered list of article IDs
  createdAt: Date;
  updatedAt: Date;
}

System Details

• Database SQLite via better-sqlite3, with sqlite-vec for vector similarity search
• AI SDK OpenAI SDK (openai compatible providers), Anthropic SDK (Claude)
• Config validation Zod schema
• Markdown to HTML marked library
• Logging Pino structured logger
• CLI framework Commander.js
• Token management tiktoken for embedding token counting
• Export Markdown frontmatter, styled HTML, plain text, RSS 2.0