SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI writingstory-cli

story-cli

Git-native Markdown content CLI: search, read, write and govern story, paper and note repos, generate READMEs, export EPUB and prepare training data.

Open website

About this tool

story-cli is a zero-deployment, Git-native Markdown content management CLI that uses a simple directory convention to manage stories, papers, notes, tutorials, and other content, automatically generates READMEs, exports EPUB, and supports both Chinese and English.

Purpose story-cli is aimed at scenarios where people write in Markdown and manage their written assets with Git repositories. It organizes content into folders: each entry directory takes the form NN-name/ and contains config.json and text.md. Through this convention, the tool can uniformly handle stories, papers, interviews, notes, tutorials, API documentation, and many other kinds of written content, forming a general-purpose content hub.

Main capabilities

  • Simple directory convention: content is just folders, NN-name/ contains config.json + text.md.
  • Automatic README generation: each entry and the root directory index are generated automatically, template-driven and customizable.
  • Series grouping and ordering: display order is controlled via series / seriesOrder, and arbitrary insertions require no reordering.
  • Runtime validation: configuration is checked before building, including required fields, enums, and formats.
  • Compliance checking: story validate checks directory naming, UTF-8, duplicate sequence numbers, and schema according to the Story-Repo specification.
  • Related stories: story link manages weak associations; story build automatically suggests candidate associations within the same series.
  • Bilingual support: Chinese and English content + automatically generated localized READMEs.
  • Chapters + word count: automatically extracts chapter titles and language-aware word counts.
  • Multi-format export: EPUB (cover rendering/typesetting styles/series metadata) / HTML / TXT / JSON / Markdown / embeddings, with support for --stdout piping.
  • General-purpose content hub: knowledge base mode (papers/interviews/notes), technical documentation mode (tutorials/API).
  • MCP Server: AI clients (Claude / Cursor) can directly read and write the content library.
  • GitHub Action: zero-configuration CI entry point (yuelinghuashu/story-cli@v1), enabling "Push → Build → Publish" in one step.
  • Watch mode: automatically rebuilds when files change.

Usage Windows users can also use sstory.ps1 generated by tory init (PowerShell version workflow): .\story.ps1 init / .\story.ps1 new -Title 'My Story' / .\story.ps1 build.

MCP Server story-cli has a built-in MCP Server, allowing AI clients (Claude Desktop / Cursor / VSCode Copilot Chat) to directly read and write the content library. AI can independently complete the full loop of "create → write → build → stats" without manually executing commands in the terminal. MCP tools have been designed from the start with the core principle of saving AI call costs: scan_stories outputs concise results by default (directory browsing saves ~80-95%), read_chapter supports on-demand truncation (continuation scenarios save ~95%+), and stats gets all data in one call (~99%). For detailed configuration and examples, see docs/mcp.md. The MCP Server reads and writes all files in the current working directory, so please run it only in trusted repositories.

Fine-tuning Data Preparation (SFT / Embedding) The structured output of the story library is naturally suited as a training data source for large models—config.json comes with category labels, export json slices precisely by chapter, and export embeddings outputs plain text chunks. Combined with --stdout + Unix toolchain, a single pipeline can convert it into standard fine-tuning format. story-cli already ensures UTF-8 encoding (automatic GBK detection warning), chapter-level slicing (avoiding semantic truncation), and complete metadata (type/series/summary can naturally be used as category labels), with no need for a secondary cleaning script.

Applicable Scenarios

  • Story/novel creation and series management
  • Knowledge base organization such as papers, interviews, and notes
  • Maintenance of technical documentation such as tutorials and APIs
  • Allowing AI clients to directly read and write the content library via MCP
  • Automated content building and publishing via GitHub Action
  • Preparing structured training data for SFT / Embedding

Limitations and Notes

  • All files must use UTF-8 encoding. When GBK/GB2312 is detected, a warning is issued but the build is not blocked.
  • The MCP Server reads and writes the current workingall files in the directory, so please run it only in trusted repositories.
  • When customizing story types/statuses and localized labels, the built-in enums already include labels, so there is no need to configure them repeatedly; deleting the file reverts to the defaults.
  • For aliases, subcommands, parameters, and category descriptions of all commands, see docs/commands.md (bilingual in Chinese and English).
  • The project includes 550+ tests, covering the scanner, series grouping, validation, template rendering, word count, internationalization, README generation, EPUB export, CLI end-to-end (smoke tests cover all commands), .storyignore, MCP protocol, JSON import, GitHub Action structure, compliance checks, related suggestions, incremental build cache, embeddings export, etc.
  • Issues are welcome (bug reports / feature suggestions, with form templates); if you are interested in contributing code, please read CONTRIBUTING.md, and learn about the project positioning in ROADMAP.md.

Related tools

Browse category