Skip to content
EidosDocsRegistry

Quick Start

The CLI does the mechanical parts: scaffolding, frontmatter, validation, the index. You do the part only you can: decide what the product is.

All of it is free, with no account: the CLI, the desktop app, the standard, every plugin, working offline, git, and your own agents. Eidos online, when a team wants its copies kept in step, is free to read and comment on without limit; you pay only to edit online past the free plan, or for extra storage. Plans → · Pricing →

  1. Install the CLI

    Section titled “Install the CLI”
    Terminal window
    curl -fsSL https://eidosmd.com/install | sh      # macOS and Linux
    irm https://eidosmd.com/install.ps1 | iex       # Windows, in PowerShell
    eidos --version

    The CLI is one program with nothing to install before it: no Node, no npm. The script checks the download against its published checksum, puts eidos in your own folder (~/.local/bin, or %LOCALAPPDATA%\Programs\eidos on Windows) with no administrator, and adds it to your PATH. With Eidos MD installed, Put eidos on the PATH… gives you the same command without the script.

  2. Create a project

    Section titled “Create a project”
    Terminal window
    eidos install @BuildableWorks/software --group identity --product "My Product"

    A project is the folder your blueprints live in, and install makes it in the folder you run it in, whatever that folder already holds, a code repository included: it copies a starting framework (a seed) there, shows its plan, and asks before writing. To give the project a folder of its own, name one after the source (eidos install @BuildableWorks/software docs/product). Pick the nearest seed; everything it gives you is reshapeable later.

    Seed For
    @BuildableWorks/software A product, service, or system being built
    @BuildableWorks/book A book, long-form argument, or course
    @BuildableWorks/research A question, a study, a programme of inquiry

    Settle two things now, because both are awkward to change later: where the project goes (the folder you run install in, or the one you name; any name works) and the naming convention (--naming kebab-case, the default, TitleCase, or "Title Case"). Naming →

    • Directorymy-product/
      • README.md the front door
      • Directory.eidos/ the framework
        • Framework.yaml folders, properties, vocabulary, the index
        • Directorytemplates/ one body template per variant
          • …
        • Directoryroles/ how an agent talks to each kind of person
          • …
        • me.md who you are (local, gitignored)
      • Directoryassets/ images and documents the blueprints link to
        • …
      • Directoryframes/ what the whole product is: one blank frame per kind
        • …
      • Directoryspecs/ the units, grouped one level deep
        • Directoryidentity/
          • …

    The README, the frames, and the specs are the project’s Core: the part that defines the product, which grows as you write blueprints and keep records for them. .eidos/ is the framework, the shape the Core takes. The Core →

    install writes no prose. The README’s one-liner, each group’s description, and every frame are yours.

  3. Say who you are

    Section titled “Say who you are”
    Terminal window
    eidos roles
    eidos whoami --role developer --ownership "the whole product" --experience deep --capacity fluent

    This writes .eidos/me.md. An agent reads it before acting to decide how to respond. Blank is fine. Roles →

  4. Fill the frames

    Section titled “Fill the frames”

    The frames describe the whole product: for software, its architecture, audience, criteria, and market. Every other blueprint is judged against them. Fill what’s known; leave the rest. Frames →

  5. Scaffold a blueprint

    Section titled “Scaffold a blueprint”
    Terminal window
    eidos new specs "Resume Playback" --group identity --variant micro --summary "Returns a viewer to the exact second they stopped."

    The file is born conforming: frontmatter from the properties that apply to specs, body from the micro template, filename in your convention, a permanent id inside. Start on the light variant; grow into full when the fuller sections earn their place.

  6. Write it

    Section titled “Write it”

    Open the file and work through the sections. Two things decide whether it is any good:

    • Lead with ## Intent: why this exists, and who has the problem. If the intent changes substantially, you have a different blueprint.
    • Write ## Out of Scope second, not last. It is where scope is held. Why →

    No tool will do this part. new scaffolds, check reports, an agent asks and formats. None of them decides what the product is. Working with agents →

  7. Check, index, browse, commit

    Section titled “Check, index, browse, commit”
    Terminal window
    eidos check
    eidos index
    git add . && git commit -m "add product blueprints"

    check reports what is missing or malformed: a review to act on, not a gate. index rebuilds the index inside Framework.yaml. To browse the project, open its folder in Eidos MD. Commit all of it; the seeded .gitignore keeps me.md out.

With an agent

Section titled “With an agent”
Terminal window
eidos agents --write

This puts a short note in AGENTS.md so any coding agent with a shell reads eidos instructions before touching a blueprint. Agents →

From here

Section titled “From here”