These are the philosophical approaches behind our CLI design

Our CLI is a command known as seed which will be available from your terminal, and usable by agents with "skills"

Self Documenting

The command line interface should teach you how to use it. For both agents and humans, you can start using the CLI before you know how to use it.

For example, when you run seed without any arguments, or when you are missing some arguments, it should explain what you can do from this area of the CLI.

Simple

We should avoid any complexity that we possibly can.

For example, if the user types seed hm://... then we can infer that the user is trying to read that URL or at least get metadata about it.

Flexible

The user may attempt to do one thing in many ways, and we should support as many of them as possible.

For example if the user is trying to create a comment, both of these workflows should be considered valid:

seed hm://DOC_URL add-comment -m "My Comment Text"
seed create comment -m="My Comment Text" -target="hm://DOC_URL

And there may be more.

Markdown First

Humans and Agents both like to read markdown. Which is more readable than our raw JSON format.

The CLI can provide front matter to display metadata.

By default the CLI will provide documentation and content. But when the -q flag is provided, the documentation/info will be excluded, and it will only provide MD+frontmatter.

We will also support JSON workflows, with the —json flag.

Compatible Workflows

Match the workflows of the Desktop app. For example: when creating new Documents, we should edit the parent Doc and add a card embed

Cautious Workflows

We should have a confirmation step before signing. If you attempt to write data without a -y flag, then it is considered a "dry run". Then you must re-run with -y to confirm the signing and publishing.

We should also have draft states for documents and comments. This will allow the agent and user to locally iterate on their content before it is signed and published.

Compliant Workflows

Follow conventions around stdout/stderr. Error codes.

We should also follow certain CLI conventions such as -h and -q and -y

The CLI should be non-interactive. We can maybe introduce a different interactive CLI one day

Draft Dispute

In our CLI design discussion there was a dispute. Should we have a draft state for document edits, or not? This means the CLI is not stateless (but it already wasn't, because of keys). But it would al