Commands

eidos <command> --help prints the same with examples. Every root-bound command takes --root <path>; without it the root is found by its .eidos/ marker from the working directory. Commands that read take --json for stable, snake_case output.

Exit codes: 0 done, 1 the check found errors (or an index is stale under --check), 2 the command could not run.

eidos install

Create a root, or pull pieces of a framework into one that exists. The plan is always shown before anything is written.

eidos install                                                   # asks each answer in a terminal
eidos install @BuildableWorks/software --group identity --product "Care Connect" --yes
eidos install @BuildableWorks/book docs/book --naming "Title Case" --yes
eidos install @BuildableWorks/research --collection investigations --yes   # into the root you are in
eidos install acme/[email protected] --path docs/blueprints --role reviewer --yes
eidos install ../other-root --all --plan                        # print the plan, touch nothing

A source is one of:

• A Registry package, @owner/name or @owner/name@<version>. The three seeds are packages; they are served from the copy inside the CLI when the versions match or with --offline. The Registry →
• A GitHub owner/repo@<tag> or git URL, with --path <folder> naming the root inside it.
• A repository on this machine, <path>@<tag>, with --path.
• A folder, read as it is.

With no source, in a terminal, the walkthrough lists the bundled packages and the Registry’s, each with its description; the Browser’s Registry page lists the same and includes from them into the root you are in.

Option	Meaning
--collection <name>	Pull one collection: its entry, variants, templates, grouping, scoped properties, and folder. Repeatable
--variant <collection.variant>	Pull one variant and its template into a collection the root has. Repeatable
--role <name>	Pull one role file. Repeatable
--top-level <title>	Pull one top-level document and its file. Repeatable
--all	Take everything the root lacks
--plan / --dry-run	Print the plan and stop
--yes	Confirm without asking
--on-conflict current|incoming	Resolve every conflict the same way. A conflict is a name both sides define differently
--force	Treat every skip (a name both sides define the same) as a conflict
--offline	Bundled packages and local folders only; fetch nothing, send nothing
--naming <convention>	New root: kebab-case (default), TitleCase, or "Title Case"
--group <name>	New root: a starting group under the grouped collection. Repeatable
--product <name>	New root: fills the README’s placeholder
--no-framing	New root: leave out the framing collection
--strict / --no-strict	New root: whether a warning fails eidos check, kept with the root
--no-agents	New root: write no AGENTS.md pointer
--json	The source, the plan, every write, skip, and conflict, and the check

On a root that exists, every name is converted into the root’s naming convention, the framework document is edited with its comments kept, then the index is rewritten and eidos check runs. A second run with the same arguments writes nothing.

One request after a Registry install

After a Registry package installs, the CLI sends one POST to eidosmd.com/api/installs/@owner/name with the package name and nothing else, so the Registry can show install counts. Skip it with --offline or by setting EIDOS_NO_TELEMETRY. No other source sends anything.

eidos init remains for one release as a hidden alias of install from a bundled seed.

eidos new

Scaffold one blueprint: frontmatter from the properties that apply to the collection, body from the variant’s template with its guidance, filename in the naming convention, a permanent id.

eidos new specs "Session Management" --group identity --summary "Keeps a signed-in user signed in."
eidos new specs Passkeys --variant micro --set status=Intake --set tags=auth,security
eidos new frames Market --dry-run

Option	Meaning
--variant <name>	One of the collection’s variants; default is the collection’s default
--group <name>	The sub-folder
--id <id>	The permanent id, one token in any form; default is a new B- and four characters, such as B-1AC3, unique in the root
--summary <line>	The one-line summary, so the index lists it at once
--set key=value	A property value at creation; repeatable; lists are comma-separated
--dry-run	Print the file instead of writing it

Required properties are generated blank; an optional one is written only when --set or --summary gives it a value. It refuses a taken id or an existing file.

eidos draft

A blueprint started before it belongs to a collection: the file new would write, kept with the CLI until it is published, in no index, listing, or check.

eidos draft new specs "Session Management" --group identity       # .eidos/plugins/eidosmd/drafts/, shared with the root
eidos draft new specs "A rough idea" --private                     # local/drafts/, private, never committed
eidos drafts                                                        # every draft, with the collection each is meant for
eidos drafts --search passkeys                                      # the drafts holding every word
eidos draft move a-rough-idea shared
eidos draft set a-rough-idea --for frames --group ""
eidos draft publish session-management                              # into its collection under new's rules, then the index
eidos draft discard a-rough-idea

publish needs the id free, converts the name to the root’s convention, and notes a group the collection does not declare. The browser offers the same from the New blueprint form and the reader’s head.

eidos check

Validate the whole root, or the named blueprints, against the root’s own framework.

eidos check
eidos check specs/identity/login.md
eidos check --strict                # this run: warnings fail too
eidos check --json

Errors are wrong on any reading: frontmatter that does not parse, a missing id or title, a duplicate id, a variant the collection does not declare, a link to a file that does not exist, a template the framework names but lacks, a region with no closer.

Warnings are gaps to surface, never refuse: a required property missing or empty, a value off a property’s options, a property no block declares, a work-tracking field, a section the template declares but the body lacks, an unknown section (only when the root asks, below), sections out of order (a heading the template does not declare is skipped), a grouping value that does not match its folder, a frame nobody has written, a stale index, a version gap, and anything at the root the framework document does not declare (or declares and is not there).

Whether a warning fails the check is the root’s setting (eidos setup --strict on|off, kept in git so CI and every machine agree). --strict and --no-strict override one run.

The section rules are the root’s too, each a switch in the same file. A heading the variant’s template does not declare (section-unknown) is not reported unless the root turns it on (eidos setup --warn-unknown-sections on): a template is the starting point and the guide to a complete blueprint, not a fence, so extra headings are the owner’s to add. A declared heading the body lacks (section-missing) and declared headings out of order (section-order) are reported unless turned off (--warn-missing-sections off, --warn-section-order off).

eidos index

Rebuild the index key inside Framework.yaml, one list per collection, touching nothing else in the document.

eidos index
eidos index --check                 # write nothing; exit 1 if stale

A blueprint without a summary is listed with a null summary and named on stderr. It is never invented.

eidos framework, list, show

eidos framework                     # version, naming, folders, properties, vocabulary
eidos framework --as yaml           # the document, normalized, with guidance as comments
eidos list specs --group identity --where status=Draft
eidos list --search B-5KFM          # by its id; every word of a search, in any case
eidos show login                    # by id, filename, or path
eidos show login --json             # properties and sections parsed out

--where key=value matches a property case-insensitively; a list property matches any item. --search <words> keeps the blueprints holding every word, in any case and any order, in the id, the title, the summary, or a property’s value, what the page’s search box over a table finds; it never reads the body. Find a blueprint this way rather than by searching the files.

eidos property

One blueprint’s frontmatter from the shell, so nobody opens a file to flip a value.

eidos property get @login
eidos property set @login status Done
eidos property set @login tags auth,security
eidos property unset @login depends_on

The blueprint is @<id>, a path, or a filename. A value is coerced to the property’s declared type. A property the table does not declare for the collection, a tool’s own, or a value off the options is refused unless --force. --dry-run prints the frontmatter as it would be.

eidos reid

New generated ids for blueprints, the one way an id changes.

eidos reid @login                   # one blueprint, or several
eidos reid --all                    # every blueprint whose id is not already B- and four characters

Each blueprint gets an id like B-1AC3, unique in the root, and every reference a plugin keeps to the old one follows: a comment thread’s target, a canvas node, a task’s blueprints, an asset’s links. The files keep their names, and links between blueprints are paths, so they are untouched. The plan is printed first, as for configure:, with --dry-run, --yes, and --json. A plugin that is off and keeps files is named in the plan, since it cannot follow.

eidos move

A blueprint moved to another group of its collection.

eidos move @login billing           # the blueprint, as show names one, and a group its collection declares

The file goes into the group’s folder with its name and its id kept, the grouping’s property is set to the group where the collection declares one, and every link in the root that pointed at the old path follows. The plan is printed first, as for configure:, with --dry-run, --yes, and --json. Move blueprint to… in a reader’s ⋮ runs the same plan.

eidos configure:<noun>

The framework, edited from the shell. Every change prints a plan (each entry, key, file, and link it touches, and every value that will be gone) and asks.

Noun	Operations
property	add, show, rename, set, remap, remove
collection	add, show, rename, remove
folder	add, show, rename, set, remove
group	add, rename, remove
variant	add, rename, set-default, remove
term	add, set, remove
doc	add, rename, set, remove
role	add, show, rename, remove

eidos configure:property add team --type Text --applies-to all --required --meaning "Owning team."
eidos configure:property add tier --type Text --options Core,Extended --meaning "How central the unit is."
eidos configure:property rename status maturity --dry-run
eidos configure:property remap maturity Draft=Nascent Done=Mature --yes
eidos configure:collection rename specs units --unit unit
eidos configure:folder add assets --description "Images the blueprints link to."
eidos configure:folder add exports --owned-by @acme/exports --description "What the exporter writes."
eidos configure:group rename specs cli cli-core
eidos configure:variant add specs api --from micro
eidos configure:doc rename "Design Principles" Principles
eidos configure:role rename developer engineer

Switch	Meaning
--dry-run	Print the plan and stop
--yes	Proceed without asking
--force	Proceed where values or files will be gone, or through a conflict the plan names
--preserve	On a remove: leave the files or keys on disk for check to report as undeclared

A rename reaches everywhere the name appears: every blueprint’s frontmatter, every link in the root, me.md, the users, and this CLI’s settings. A move is a git mv where git is on. Narrowing a property’s options names every blueprint with a value off the new list and needs --force. After any change the index is rewritten and check runs. Without a terminal and without a switch, a command exits 2 naming the switch, so an agent learns it from the error.

eidos migrate

Move a root to the standard this CLI carries, mechanically.

eidos migrate --dry-run
eidos migrate

It renames what moved between versions, rewrites the standard’s properties.core block, sets eidos_version, and reports what only the owner can decide (a folder or file at the root nothing declares). A root already current is left alone. Versioning →

eidos setup

The CLI’s own settings for a root, none of them the standard’s: the product the root defines, which plugins are on, whether a warning fails check, the people who work in the root, and who this machine acts as.

eidos setup                          # a menu of the plugins, then the questions, in a terminal
eidos setup --product "Care Connect" # what the Home and the desktop app call the root; "" goes back to the repository's name
eidos setup --enable backlog --disable terminal --strict on --add-user "Ada Lovelace" --alias ada --role developer --email [email protected] --as ada
eidos setup --warn-unknown-sections on --warn-section-order off  # which section rules warn

Writes .eidos/plugins/eidosmd/settings.yaml (shared with the root) and local.yaml (yours, gitignored).

eidos plugin

eidos plugin                         # every plugin: title, version, on or off, where its switch is written
eidos plugin enable backlog          # plugins.backlog: true in settings.yaml; a plugin that keeps a root folder declares it
eidos plugin disable terminal --me   # private, in local.yaml
eidos plugin set plato agent codex   # one declared setting, to the file its scope names (a me setting in local.yaml); --unset for the default
eidos instructions backlog           # a plugin's own guide, while it is on

Off, a plugin registers nothing; its folder, settings, and regions stay for the day it comes back. Plugins →

Plugin commands

Each plugin that is on mounts its command under a Plugins heading in eidos --help; eidos <plugin> --help prints it with examples.

eidos canvas new "Product Map"       # .eidos/plugins/canvas/product-map.yaml (--private for local/); list, show <id> [--page], move <id> shared|private, schema
eidos comments @login                # the threads on a blueprint; add <target> <text> [--section] [--item] [--reply] [--as], resolve, delete, project
eidos backlog --status "In Progress" # the tasks; add <title> --for @login [--type], show, set, check <task> <n>, promote, types, sections, export, draft:*
eidos decisions --unconfirmed        # the inbox; add <decision> --for @login [--type] [--task] --as <alias>, show, set, confirm, types, statuses, project, remove
eidos assets --for login             # the files; show, add <file>, link <path> --to @login, set --title|--name, remove
eidos linter --fix                   # the markdown files that drifted from the root's rules, settled

A target for Comments is a blueprint (@<id>, a path, a filename), a doc, or <host>:<id> (backlog:<task>, canvas:<page>, decisions:<id>). Plugins →, one page per plugin

eidos version

eidos version                                   # the root's versions, newest first
eidos version record 1.0.0                      # a row naming HEAD
eidos version record 1.0.0 --commit a1b2c3d --tag   # names that commit and tags it blueprints/1.0.0

A version is a fixed point: a name for a commit, so a team can later read the root exactly as it was (the scope a client signed off, what a release was built against). Git already holds every file; the row gives the commit a name. It is this CLI’s record, in .eidos/plugins/eidosmd/versions.yaml, written only when asked. The tag prefix is versions.tag_prefix in settings.yaml, blueprints/ by default.

eidos views

eidos views              # every saved view: its id, its name, the address that opens it, shared or private
eidos views --json       # { views[{ id, name, page, query, scope }] }
eidos views move V-7K2M private   # move a view to your local.yaml, or back with shared; its id, filters, and sort kept

The views saved in the browser from a filtered board or table (Save as view): the shared ones first, from .eidos/plugins/eidosmd/views.yaml, committed with the root, then yours, from views in local.yaml, never committed. A view is made, renamed, and deleted in the browser, and moved between shared and private there or with eidos views move; the command lists them, so an agent can hand a person the address of one under eidos browser. The Backlog’s My work, By status, and By type are the views every root starts with and are kept in neither file. Saved views →

eidos browser

eidos browser
eidos browser --port 7000 --no-open

The root in a local web page on 127.0.0.1. The browser →

eidos roles, whoami

eidos roles
eidos whoami --role developer --experience "new to this product" --capacity fluent
eidos whoami --clear

whoami writes the private, gitignored .eidos/me.md. Roles →

eidos users

eidos users                          # every user: name, @alias, role, email, and whether one is an agent
eidos users add "Plato" --agent       # add one on the fly; only the name is needed
eidos comments add @login "…" --as plato   # a comment signed by that user, not by you

The people and agents who work in the root, the same list as the Users settings page (users in .eidos/plugins/eidosmd/settings.yaml). add takes a name and nothing else by default: the alias comes from the name, a role is optional, and a user already there is reported rather than added twice. An agent adds itself once with --agent, then signs every comment as itself with --as <alias> (or EIDOS_USER), never as the person it works for. Comments →

eidos instructions, agents, standard, seeds

eidos instructions                  # list the guides
eidos instructions overview         # required first read for an agent
eidos agents --write                # a pointer in AGENTS.md (or --file CLAUDE.md)
eidos standard                      # the text of EIDOS.md this CLI carries; --version for the number
eidos seeds                         # the bundled seeds, their collections and variants

Agents →