Skip to content

The CLI

storyletengine is the command line. It runs the same operations the editor does, so a CI gate sees exactly what the editor sees. Use it to gate a pull request, run a build, or script a hand-off.

Download a standalone binary for your platform from the Download page. It is one file, with no Node installation needed and nothing else to install alongside it.

Terminal window
chmod +x ./storyletengine-macos-arm64
./storyletengine-macos-arm64 validate ./my-project.storylets

The binaries are how the CLI ships for now: it isn’t on npm yet, so there’s no npx for it. Put the binary somewhere on your PATH and call it storyletengine if you want the short form. The JS runtime is on npm (@storylet-studio/runtime), and every runtime also ships as a zip on the Download page.

Every command that writes a project file writes through your version control (checking a file out first, adding new files), so a locked or read-only file fails the write instead of being overwritten. merge is the exception: it runs inside your version control’s own merge, so it writes its output directly. Exit codes are consistent: 0 success, 1 the operation found problems or failed, 2 a usage error. fmt is an alias for format.

Most commands take a project path as their last positional argument, defaulting to the current directory. You can point at the .storylets folder or anywhere inside it.

A flag that takes a value takes it inline as well: --runs=50, --where=area=docks. storyletengine <command> --help prints one command’s usage, and --version prints the version. A usage error says what is wrong and then the command’s whole usage, every line starting usage:.

Every command that loads the project prints the problems the load found. A load error (a shard that doesn’t parse, say) stops export, export-html, links, coverage and share-scopes with exit 1, because what they would build or report would be missing whatever failed to load.

storyletengine init [dir] [--name X] [--kit starter|map-story|action-game] [--vcs git|perforce|plastic|svn|none] [--bundle commit|ignore]
storyletengine new box [path] [--kit blank|rpg|dialogue|jobs|stash|codex|news|acts]
storyletengine validate [path]
storyletengine format [path] [--check] (alias: fmt)
storyletengine export [path] [-o file] [--map|--no-map]
storyletengine export-html [path] [-o file]
storyletengine export-xlsx [path] -o FILE
storyletengine peek <box> [path] [--where group=tag ...] [--n N] [--set path=value ...] [--seed N] [--deal-all]
storyletengine deal <hand> [path] [--set path=value ...] [--seed N] [--deal-all]
storyletengine resolve <query> [path]
storyletengine usage <property> [path] [--json]
storyletengine contract show [installation] [path]
storyletengine merge BASE OURS THEIRS [-o out] [--json] [--path realfile]
storyletengine mergetool BASE THEIRS OURS OUT [--fallback "tool args"]
storyletengine links [path] [--deck X | --box X | --card X] [--refs] [--json]
storyletengine coverage [path] [--runs N] [--max-turns M] [--seed S] [--order least|deck] [--json] [--fail-on-gap] [--propose]
storyletengine share-scopes [path] [--at DIR]
storyletengine pack [path] -o FILE [--assets|--no-assets]
storyletengine unpack FILE -o DIR [--merge --base SENT.storyletpack]
storyletengine --version
storyletengine <command> --help

Scaffold a new project.

$ storyletengine init tavern --name "The Tavern"
initialised "The Tavern" in .../tavern.storylets
next: storyletengine export .../tavern.storylets

It creates <dir>.storylets from a GAME KIT, plus the files that keep a project tidy: .editorconfig, .vscode/settings.json, and the setup for your version control. --kit is starter (the default: one box, one hand, two cards that show the loop), map-story (a village on a drawn map, whose first scene opens the rest of it), or action-game (five boxes on one city map, the story side of an action game). Storyletter’s New Project picker offers the same kits. See the walkthrough.

Flag Does
--vcs git Writes .gitattributes (LF text, the structured merge driver) and .gitignore, and records git on the project.
--vcs perforce Writes .p4ignore, and records Perforce.
--vcs plastic Writes Plastic’s ignore.conf, and records Plastic SCM.
--vcs svn Records SVN; its ignores are a folder property, so vcs-setup.md gives the command.
--vcs none Records that the project has no version control.
--bundle ignore Keeps the compiled bundle out of version control, to build it in CI. The default, commit, commits it.

Every project gets a vcs-setup.md with the one-time steps for its system: the git config lines, the Perforce typemap, the merge tool to set. With no --vcs it covers every system, and Storyletter finds the system from the folders. See version control.

Add a box, scaffolded from a BOX KIT. A box kit is a starting point you own, fully editable the moment it lands, with no kit reference left in the files. (The other scale is a GAME KIT, which starts a whole project: init --kit, or Storyletter’s New Project picker.)

$ storyletengine new box tavern.storylets --kit rpg
added box "new-box" (rpg kit) in .../tavern.storylets

--kit is blank (the default), rpg, dialogue, jobs, stash, codex, news, or acts. Every narrated box kit carries a purpose note on every piece. Storyletter’s New Box picker offers the same eight and scaffolds identically.

The check to run before you commit or publish.

$ storyletengine validate tavern.storylets
ok: .../tavern.storylets

It checks for property references nothing declares, tag references that point nowhere, hands that don’t fill in every group their template asks for, the box’s card and outcome field declarations (a name used once, a known type, values for a list or flags, a default that fits) and the values cards and outcomes give them, every quality’s ladder (at least two stages, each named once, the default on it), map pictures missing from assets/, canonical form, a leftover merge conflict file, and bundle staleness (a committed .storyletsc whose content hash no longer matches the shards is an error). It also warns about a condition reading state nothing writes and a condition that can never hold, and, when the project is paired with Patter, checks each card against its scene.

Problems print as severity: path [where]: message. Any error exits 1, which makes this the natural pre-commit hook and CI gate.

Where the game shares its scopes, it also reads the game-scopes/ folder: a file there that won’t parse, or a scope two files both declare, is an error, and a reference into another tool’s scope that its file doesn’t allow is a warning. So is game-scopes/storylets.scopes.json being out of date, which export or a save in Storyletter fixes.

Rewrite shards into canonical form: sorted keys, one field per line, trailing commas, LF, a final newline. Files that are always written the same way are files that merge cleanly.

Every list you can arrange is sorted by id here (cards, hands, outcomes, hand templates, tag groups and their tags), and the order you arranged is written into an order field first, so running this never changes what the editor shows you.

$ storyletengine format tavern.storylets
formatted 1 shard(s)

--check reports what would change and writes nothing, exiting 1 if anything isn’t canonical. That’s the CI form. fmt is an alias. Pointed at a folder with no project in it, either form fails rather than reporting nothing to change.

format is also how a project from before the project map moves onto it, the same upgrade Storyletter offers when it opens one. The map kept in a box becomes the root map.storyletmap, every box that held a copy or placed a hand is put on the map, the other boxes’ references are rewritten to the kept map’s zones, frames and map comments move to the project, and the pictures move to the project’s assets/ folder. It prints what it did. Hand positions still kept in an old view.storyletview, from before map files, are no longer read, and it drops them. It also rewrites a card’s old copies as acrossHands.

It refuses, writing nothing, when the copies of a map disagree (a zone one has and another hasn’t, a zone drawn differently, different zone properties or starting values, or a map bound to state or required in one box and not another), when the project has more than one map, when a group or tag in some box already has the map’s or a zone’s name, or when a box that joins the map for its placed hands declares a property the map also declares, differently. Each refusal is one sentence saying what to change, and you run format again once it’s fixed. The compiler names this command when it meets a project that needs it.

Compile to the bundle.

$ storyletengine export tavern.storylets
exported .../storylet-dist/the-tavern.storyletsc

It writes to the path the project shard declares. -o file overrides it; -o - writes the bundle to standard output exactly as it would be on disk. Export compiles first and refuses to write anything on an error, including a shard that won’t load.

--map carries the project map’s drawing, meaning the zone shapes, the background pictures, and where each box’s hands stand, with the pictures written to assets/ beside the bundle. --no-map leaves them out. The zones themselves always ship, because cards and hands use them. Without either, the project’s own export.map setting decides, and its default is off, because geometry is authoring data and a shipping build needn’t carry anything it doesn’t use. The engine never reads the drawing; it’s there for a host that draws its own map. See the bundle.

Where the game shares its scopes, export also brings game-scopes/storylets.scopes.json up to date (your @story declarations, for the other tools to read), writing it only when it changed. It never creates the folder.

One self-contained, playable .html with the runtime, the Board, and the compiled bundle inlined, so it plays offline in any browser with no server and no install. Hand one file to anyone.

$ storyletengine export-html the-hamlet.storylets -o "The Hamlet.html"
wrote The Hamlet.html (128 KB)
Flag Does
-o FILE Where to write the page. Without it, the page lands beside the bundle under the bundle’s name (storylet-dist/the-hamlet.html for the example). -o - writes it to standard output.

The page is the Board, with every hand as a labelled group of cards, outcomes under the open card, Deal all hands, Next turn, Restart, and a transcript. The project map is drawn once with every box’s hands on it, the background pictures inlined as data, and a pin per placed hand carries its live card count. The bundle inside it is compiled with full metadata whatever the project’s setting, so titles and purposes show, and the player’s place is saved in that browser. Storyletter’s Publish ▸ Publish Playable HTML… writes the same page; there’s more about what to do with it in the editor tour.

The whole project as a readable Excel workbook, the thing to hand a lead for a review meeting, or a producer who wants to sort and filter.

$ storyletengine export-xlsx the-hamlet.storylets -o "The Hamlet.xlsx"
wrote The Hamlet.xlsx: 17 card(s) on 5 deck sheet(s), 25 outcome(s), 3 hand(s), 1 tag group(s)
Flag Does
-o FILE Where to write the workbook. Required.

The workbook opens on an Overview sheet (the project’s name, version, and content hash, when it was generated, counts, and an index of the deck sheets), then one sheet per deck, named after the deck. Each row is a card: Title, gameId, When, Priority, Redraw, Weight, In one hand, Across hands, a column per tag group, a column per card field, Purpose, and the card’s outcomes with their changes. After the decks come Outcomes (one row per outcome, for filtering), Hands (hand, template, When, tags, slots, purpose), and Tag groups (every tag with its properties). With more than one box, every sheet gains a Box column, and a deck title two boxes share gets the box in its sheet name.

It reads the source files, not the bundle, so titles and purposes are always in it whatever the project’s metadata setting. Storyletter’s Publish ▸ Publish Spreadsheet… writes the same workbook.

Ask the reference runtime a question about your project from the command line. Both compile the project in memory, stand up an engine and a flow, apply any overrides, and answer.

$ storyletengine deal the-inn the-hamlet.storylets
1. arrive-at-the-gate "Arrive at the Village Gate"
$ storyletengine deal the-inn the-hamlet.storylets --set 'story.act="act-1"'
1. settle-at-the-inn "Get Settled at the Inn"
2. market-bustle "Market Bustle"
$ storyletengine peek village the-hamlet.storylets --where area=village
1. arrive-at-the-gate "Arrive at the Village Gate"

deal <hand> refreshes one hand by name. peek <box> lists every card the box could deal right now, in ranking order, without dealing anything.

Flag On Does
--where group=tag peek Filter by tag, one entry per tag group. Repeatable.
--n N peek Cap the list at N.
--set path=value both Set a property before asking. Repeatable. The value is parsed as JSON5 where it parses, and taken as a bare string otherwise.
--seed N both The flow’s seed. Defaults to 0.
--deal-all both Deal every hand first, so cards other hands have claimed are already gone.

Content that names another engine’s scope (@patter.visits) needs that engine beside it. On its own the engine refuses such content, naming the scope, and the command exits 1. Where the game shares its scopes, peek, deal, and coverage stand the other engines in instead, each property at the default its tool’s file declares, so the content plays. --set can move one of them (--set patter.visits=3).

--set takes the same paths the runtime does, the owner named as you name it in a shard: story.started, world.market_day, player.hp (any host scope), value.docks.danger, box.street.heat. Where two boxes name a tag the same way, say which box the tag is in: --set value.harbour/docks.danger=3. A zone of the project map is always the short form, value.docks.danger, because it belongs to no box.

--deal-all is how you see exclusivity from the command line. With every other hand dealt first, the cards they hold don’t come up in yours.

Find the item a query names, and say where it lives.

$ storyletengine resolve arrive-at-the-gate the-hamlet.storylets
c_arrive [card] "Arrive at the Village Gate" arrive-at-the-gate Village > Arrival (village/decks/arrival.storyletdeck)
$ storyletengine resolve inn the-hamlet.storylets
c_inn_first [card] "Get Settled at the Inn" settle-at-the-inn Village > Arrival (village/decks/arrival.storyletdeck)
c_inn_road [outcome] "Ask only about the road north" ask-about-the-road-north Village > Arrival > Get Settled at the Inn (village/decks/arrival.storyletdeck)
c_inn_warm [outcome] "Ask warmly about the village's history" ask-about-history Village > Arrival > Get Settled at the Inn (village/decks/arrival.storyletdeck)
h_inn [hand] "The Inn" the-inn Village (village/hands.storylethands)

The query can be a gameId (the name your game code and the runtime’s logs use), an id (what a shard or a merge conflict file names), or a title. It tries an exact gameId first, then an id, then a title, then a partial match of any of the three, and stops at the first of those that finds anything, so an exact match is never buried in partial ones. Each hit prints id [kind] "title" gameId Box > Deck (shard). Boxes, decks, cards, outcomes, hands, hand templates, and tag groups are all findable.

It’s the same lookup Storyletter’s --at uses when you open a project at a particular item, so what the terminal says and where the editor lands can’t disagree. No match prints no match for '<query>' and exits 1.

List every place a property is read or written.

$ storyletengine usage @story.rel_blacksmith the-hamlet.storylets
read @story.rel_blacksmith When: not check_flags(@rel_blacksmith, +met) and @act > arrival Village > Arrival > Make Yourself Known at the Forge (c_forge_first)
write @story.rel_blacksmith outcome change: @story.rel_blacksmith ← set_flags(@rel_blacksmith, +met) Village > Arrival > Make Yourself Known at the Forge > Talk straight: ask if he's hiring (c_forge_straight)
read @story.rel_blacksmith outcome When: check_flags(@rel_blacksmith, +warm) Village > Gareth's Debt > The Moneylender's Men > Stand with Gareth against them (c_gm_stand)
...

A read is a card’s When or priority, a deck’s gate, a hand’s When, or an outcome’s When or change value; a write is an outcome’s change. Each line names the item it is in, as a trail from its box, and its id. Name the property as you would in a condition: @story.act, world.time_of_day, @box.village.heat, or a bare @gold, which finds that name in any scope. --json prints the uses as data. A property nothing uses prints nothing and exits 0; a project that will not compile exits 1. It is the list Storyletter’s Find window shows on its Property tab.

What each installation contract in the project depends on: the hands dealt there, the boxes ticked on a schedule, the properties a clock drives, the fields read outside the game.

$ storyletengine contract show the-park.storylets
the-park (Storylet Server 0.1.0, revision 12) (contracts/the-park.storyletcontract)
hand the-well dealt here
hand the-forge dealt here
box street the scheduler ticks it every 60s
property world.time_phase
property story.visits
field prompt the crew and the bridges read it

Name an installation to show only that one. There’s no verb for the breaks, because validate already reports them, as errors, each one naming the venue that cares. A project with no contract says so and exits 1.

The structured merge driver, an id-keyed three-way merge of storylets source files.

storyletengine merge BASE OURS THEIRS -o OUT --path REALFILE

Output is always parseable canonical source. Where the two sides genuinely clash, your side is kept and a .storyletconflict file is written beside the real shard. --path tells the driver where that real shard is, because your version control system hands it temporary filenames.

Without -o it prints the merge result as JSON. --json prints it as well as writing. Warnings (including a hand rename, which breaks game code that deals it by its old name) go to standard error. It exits 1 when there are conflicts and 2 on unparseable input, so a version control driver falls back to its own behaviour instead of trusting a guess.

Full detail on version control.

The one global merge tool Perforce, Plastic SCM and SVN allow. Storylet Studio files go to the structured merge, exactly as merge does them, and anything else goes to your usual tool.

storyletengine mergetool BASE THEIRS OURS OUT --fallback "<your merge tool>"

The four files are in the order those systems agree on: base, theirs, ours, and the output. The output is the real file, so a clash leaves its .storyletconflict beside it. --fallback is the command for everything else, with any flags of its own ("code --wait --merge"); it is given the same four files, in the same order, and its exit code is the merge’s. Without a fallback, a file that isn’t Storylet Studio source exits 2. git doesn’t need this: it calls merge per file. Each system’s line is in the project’s vcs-setup.md, and on version control.

Share the project’s scopes with the game’s other editing tools: the terminal’s version of Storyletter’s File ▸ Share Scopes with Other Tools… (see Sharing scopes between the editors).

$ storyletengine share-scopes .
wrote /work/my-game/game-scopes/storylets.scopes.json
wrote /work/my-game/game-scopes/game.scopes.json

It makes the game’s game-scopes/ folder, by default at the version-control root above the project (else beside the project), with the Storylet Engine’s storylets.scopes.json and a game.scopes.json holding the project’s host scopes (@world, and any others it declares), which the project keeps as its synced copy.

Flag Does
--at DIR Put game-scopes/ in DIR instead. When looking up from the project wouldn’t find it there, the project names it in its gameScopes field.

A folder that already exists, made by another tool, is joined rather than replaced: its game.scopes.json keeps every scope it holds, and gains each of the project’s host scopes only when it has none of that token. A project that already shares its scopes is refused, naming the folder.

Snapshot the project into one portable .storyletpack, for handing to someone who isn’t on your version control.

$ storyletengine pack . -o outbox/village.storyletpack
packed outbox/village.storyletpack
Flag Does
-o FILE Where to write the pack. Required.
--assets / --no-assets Carry the map’s background pictures too, or leave them out. Without either, the project’s export.packAssets setting decides (off unless set).

The pack carries the source shards and a manifest. It doesn’t carry the compiled bundle, which is generated and would only go stale in transit. Packing an unchanged project twice produces identical bytes.

Where the game shares its scopes, the pack also carries a read-only copy of every *.scopes.json in the game-scopes/ folder, found as the other commands find it. The folder sits outside the project, so without the copy the person you send it to would be working without the other tools’ names. A project with no folder packs exactly as before.

Explode a pack back into shards, or fold a returned one into your project.

$ storyletengine unpack village.storyletpack -o ./village
unpacked: village/encounters/box.storyletbox
unpacked: village/encounters/decks/docks.storyletdeck
...
unpacked: village/saltmarsh.storyletproj
6 shard(s) -> ./village
Flag Does
-o DIR Where the shards go, or the project to merge into. Required.
--merge Fold a returned pack into the project at -o instead of extracting.
--base SENT The pack you sent, used as the common ancestor. Required with --merge.

A pack that carries the game’s scopes unpacks them into game-scopes/ inside the project folder, where the other commands look first, so validate checks @patter names there as it does at home, and peek, deal, and coverage can stand the other engines in.

With --merge, each shard goes through the same id-keyed three-way merge as merge, so you and the other author can edit different fields of the same card and both edits survive. A conflict writes your version plus a .storyletconflict file and exits 1.

$ storyletengine unpack returned.storyletpack -o . --merge --base outbox/village.storyletpack
merged: encounters/box.storyletbox
merged: encounters/decks/docks.storyletdeck
...
6 shard(s) -> .; 0 conflict(s), 0 warning(s)

--merge without --base is a usage error, because with no ancestor there’s no merge to do, only an overwrite.

--merge never writes back the returned pack’s copy of the game’s scopes: your game-scopes/ folder is the one that counts. The exception is the World properties. If the other author changed them, the merge writes the merged list to your game.scopes.json too and says so, because otherwise your next save would copy the old list back into the project and lose their edit without a word:

$ storyletengine unpack returned.storyletpack -o . --merge --base outbox/village.storyletpack
merged: encounters/box.storyletbox
...
merged: saltmarsh.storyletproj
updated the game's World properties: /work/village/game-scopes/game.scopes.json
6 shard(s) -> .; 0 conflict(s), 0 warning(s)

If game.scopes.json won’t parse, the merge leaves it alone and warns instead.

A pack may arrive from outside your team, so entry paths are checked before anything is written. An entry that would land outside -o is refused and nothing is written.

Which cards can turn which other cards on and off, worked out from conditions and outcomes alone. No playthrough, no simulation, nothing written.

$ storyletengine links saltmarsh.storylets
links: 4 card(s), 6 edge(s) - 4 enable, 2 disable, 0 influence, 0 reference
Ambush at the ford disable A light-fingered stranger [@story.reputation by flee through the deck gate]
Ambush at the ford enable A light-fingered stranger [@story.reputation by stand-and-fight through the deck gate]
Ambush at the ford disable The mysterious stranger [@story.reputation by flee through the deck gate]
Ambush at the ford enable The mysterious stranger [@story.reputation by stand-and-fight through the deck gate]
A light-fingered stranger enable Ambush at the ford [@story.reputation by caught through an outcome gate]
A light-fingered stranger enable The mysterious stranger [@story.reputation by caught through the deck gate]
Flag Does
--deck X Only that deck’s cards, and only edges between them.
--box X Only that box’s cards.
--card X Analyse everything, centred on that card (what the editor’s Links… view asks).
--refs Also report reference edges: two cards read a property nobody writes.
--json The whole graph.

Four kinds of edge:

Class Means
enable the writer makes the reader’s condition more likely to be true
disable more likely to be false
influence it touches state the reader reads, but the direction can’t be worked out statically (a computed value, or a nudge towards an exact number)
reference both read a property neither writes. Off unless you ask

Every edge names which outcome does the writing. One card’s outcomes often push a property in opposite directions, so the same pair of cards can legitimately get both an enable and a disable edge: “enabled if you stand and fight, disabled if you flee”.

@hand isn’t analysed. A hand’s properties are put together at the deal, from its tags, its own properties, and the criteria it was dealt with, so two cards reading @hand.danger may not be talking about the same hand at all. The command says so in a warning and leaves those edges out.

A deck-scoped run can be empty even when its cards are busy, because the edges may all cross into other decks. Run it without --deck to see those.

Seeded playthroughs that report what your content can actually reach.

$ storyletengine coverage saltmarsh.storylets --runs 20 --seed 1
coverage: 20 run(s), seed 1, max 100 turns/run, 2000 turns, 2000 plays
no input drivers: content gated on @world (or any host scope) reads as never dealt
runs ended: 0 saw everything, 20 ran to the turn cap, 0 stuck
cards dealt 2/4, played 2/4; outcomes played 2/5
never dealt 2, rarely dealt 0 (under 5% of runs), dealt but never played 0
hand docks-street: saw 2/3 cards that can come up here, over 2051 deal(s) in all runs
runs dealt = share of runs that dealt the card at least once; dealt, played = times across all runs; n/a = no outcomes
‼ never dealt ? never dealt, gated on state nothing sets ~ rarely dealt (under 5% of runs) ! dealt, never played
least reached first
runs dealt dealt played card
? 0% 0 0 [Docks] ambush-at-the-ford
gated on @hand.danger, written only by ambush-at-the-ford, which never came up either
? 0% 0 0 [Market] pickpocket
gated on @story.reputation, written only by ambush-at-the-ford, pickpocket, which never came up either
100% 51 20 [Market] mysterious-stranger
100% 2000 1980 [Docks] rat-job
never played: ambush-at-the-ford/flee
never played: ambush-at-the-ford/stand-and-fight
never played: pickpocket/caught

The second line names the host scope properties (@world, …) the run drove, or says that none were. A run with no drivers reports host-gated content as never dealt, which is true of the run, not of the content.

The table lists every card with its deck in brackets, least reached first. The never dealt lead, then the rarest, down to the ones every run deals. runs dealt is the share of runs that dealt the card at least once. dealt and played are times across all the runs, so they can be far more than the number of runs. A card with no outcomes reads n/a for played. The marks are ‼ never dealt, ? never dealt with a reason on the lines under it, ~ dealt in fewer than 5% of runs, and ! dealt but never played. --order deck lists the cards deck by deck, as authored, instead. See Coverage testing for how to read them.

Flag Does
--runs N How many playthroughs.
--max-turns M Cap the turns per run.
--seed S The seed. The same seed always reproduces the same run.
--order least|deck Least reached first (the default), or deck by deck as authored.
--json The full report as JSON.
--fail-on-gap Exit 1 on any never-dealt card, unprovided @hand read, or runtime warning. The CI form.
--propose Print a proposed coverage block instead of running. The run’s own flags do nothing with it, and it says so.

--propose derives drivers from your conditions (the literals they compare against, plus declared boolean and enum domains, skipping anything an outcome writes) and prints a block to paste into the project shard. It’s the same derivation behind Storyletter’s Add coverage drivers and Propose from the cards buttons. See coverage testing.

Open source under the MIT licence, made by .