@cyoa/cli

A command-line interface (CLI) for the @cyoa/engine. This tool allows you to validate, run, and inspect story files from your terminal.

Installation

You can install the CLI globally using your favorite package manager:

npm install -g @cyoa/cli
# or
yarn global add @cyoa/cli
# or
pnpm add -g @cyoa/cli

Usage

The CLI provides three main commands: validate, run, and inspect.

validate

The validate command checks a story file for errors and ensures it conforms to the story schema.

cyoa validate <file>

• <file>: The path to your story file (e.g., story.json or story.yaml).

If the story is valid, you'll see a success message. If there are any issues, the CLI will print a list of errors and warnings.

run

The run command lets you play through a story in your terminal.

cyoa run <file> [--seed <seed>]

• <file>: The path to your story file.
• --seed: An optional seed for the random number generator, allowing for reproducible playthroughs.

The CLI will display the text for each beat and a list of available choices.

inspect

The inspect command allows you to view the contents of a saved game state file.

cyoa inspect <file>

• <file>: The path to a saved game state file (in JSON format).

This is useful for debugging or getting a snapshot of the game's state at a particular point.

Example Story

Here's a simple story in YAML format that you can use to test the CLI:

my-story.yml

id: my-first-story
version: 1.0.0
start: intro
knots:
  main:
    beats:
      intro:
        text: You are in a dark room. There is a door to your left and a door to your right.
        choices:
          - text: Go left
            target: left_door
          - text: Go right
            target: right_door
      left_door:
        text: You found the exit!
      right_door:
        text: You fell into a pit!

You can then run this story with the following command:

cyoa run my-story.yml