Storymaps CLI

Turn your storymaps.io diagrams into YAML files you can version-control, diff in pull requests, and sync with the server - all from your terminal.

Story maps are structured data. The CLI lets you export the structure behind the diagram, edit it as code, and push changes back to the browser.

# What a story map change looks like in a pull request
 slices:
   - name: MVP
     stories:
       Checkout:
         - name: Payment form
           status: done
+        - name: Apple Pay
+          status: planned
+          tags: [payments, mobile]

Install

npm install -g storymaps

Or clone and link locally:

git clone https://github.com/jackgleeson/storymaps-cli.git
cd storymaps-cli
npm install
npm link

Quick Start

storymaps init                        # create a new storymap.yml
storymaps open                        # open it in the browser

Or pull an existing map:

storymaps pull storymaps.io/abc123    # download as YAML

Edit the YAML, then push it back:

storymaps diff                        # see what changed
storymaps push                        # sync to the server

Status

See the project status in a snapshot:

> storymaps status

Mobile Banking
id: 6u0kmy98

Overall Progress
  ████████████░░░░░░░░ 37/62 stories (60%)
  58 points total

Slices
  MVP      ███████████████ 30/30 (100%) | 52pts
  V1       ██████░░░░░░░░░  7/18 (39%)  | 6pts
  V2       ░░░░░░░░░░░░░░░  0/14 (0%)   1 blocked

Status
  ● done: 37  ● in-progress: 8  ● planned: 16
  ● blocked: 1  ○ no status: 0

Blocked
  ● Scan QR code

Non-task cards (notes, questions) are excluded from counts based on the legend.

Commands

init

storymaps init
storymaps init --site storymaps.yourcompany.com

Creates storymap.yml and registers it on the server. If you're offline, the file is created locally and push will register it later.

open

storymaps open                        # open local storymap.yml in the browser
storymaps open storymaps.io/abc123    # open a specific remote map

pull

storymaps pull                        # uses id/site from storymap.yml
storymaps pull storymaps.io/abc123    # pull a specific map

Shows a summary of changes before overwriting.

push

storymaps push                        # push local changes to the server

If the file has no id, a new map is created on the server. Conflicts are detected using ETags. If the remote has changed since your last pull, you'll be prompted to pull first. Locked maps prompt for the password.

diff

storymaps diff                        # summary of changes vs remote
storymaps diff --full                 # full line-by-line diff
storymaps diff file1.yml file2.yml    # compare two local files

status

storymaps status                      # progress overview of storymap.yml
storymaps status other.yml            # progress overview of a specific file

Progress overview: slices, status counts, and blocked stories.

log

storymaps log                         # activity log for storymap.yml
storymaps log storymaps.io/abc123     # activity log for a specific map

Shows timestamped activity entries with source labels (cli, mobile, web).

lock / unlock

storymaps lock                        # lock the map with a password
storymaps unlock                      # session unlock
storymaps unlock --remove             # permanently remove the lock

validate

storymaps validate storymap.yml       # check YAML structure

convert

storymaps convert storymap.yml --to json                    # YAML to JSON
storymaps convert storymap.json --to yaml --out storymap.yml # JSON to YAML

YAML Format

name: Mobile Banking
id: 6u0kmy98
site: storymaps.io

steps:
  - Find App
  - Log In
  - Start Transfer
  - Select Recipient
  - Enter Amount
  - Review
  - Confirm
  - Done

users:
  - name: Bank Customer
    step: Find App

activities:
  - name: Send Money
    step: Find App

legend:
  - color: "#fef08a"
    label: Tasks
  - color: "#a5f3fc"
    label: Notes
  - color: "#bef264"
    label: Questions
  - color: "#fecdd3"
    label: Edge cases

slices:
  - name: MVP
    stories:
      Find App:
        - name: App store listing with screenshots
          status: done
          points: 2
          tags: [ux]
      Log In:
        - name: Email and password login
          status: done
          points: 3
          tags: [security, auth]
        - name: Account locked after failed attempts
          color: "#fecdd3"
      Select Recipient:
        - name: Search contacts
          status: done
          points: 2
          tags: [ux]
        - name: Recent recipients
          status: done
          points: 2
          tags: [ux]
      Confirm:
        - name: Confirm button
          status: done
          points: 1
          tags: [ux]
        - name: SMS one-time code
          status: done
          points: 3
          tags: [security, auth]
          url: https://en.wikipedia.org/wiki/Payment_Services_Directive

  - name: V1
    stories:
      Log In:
        - name: Biometric login
          status: done
          points: 3
          tags: [security, auth]
        - name: Remember device
          status: done
          points: 2
          tags: [security]
      Select Recipient:
        - name: Add new recipient
          status: done
          points: 3
          tags: [payments]
        - name: Mark as favorite
          status: in-progress
          tags: [ux]

Cards support: name, body, color, status (done / in-progress / planned / blocked), points, tags, and url.

Self-Hosting

The CLI works with any storymaps.io instance:

storymaps init --site storymaps.yourcompany.com

See the main project README for setup instructions.

Licence

AGPL-3.0 - see LICENCE for details.