sfora-cli

Your sfora workspace as a markdown filesystem — a Linear for your agents. Every post, task, and doc is a markdown file under /projects/<slug>/…, so you (and your agents) can post, task, doc, ls, cat, and grep your work — or echo > straight into it. Ships first-class verbs, an interactive shell, and an MCP server (--mcp) so agents in Claude / Cursor operate sfora natively.

sfora new "Acme"                          # create a project
sfora post plan.md --project acme        # push a markdown plan as a post
sfora task spec.md --project acme         # …or a task on the board
sfora cat /projects/acme/board/01-todo/0042-fix-login.md
sfora url /projects/acme/docs/kickoff.md  # where it lives on the web

Under the hood it maps a Unix view onto sfora's /v1/fs HTTP API (a sandboxed shell interpreter backs the interactive mode).

/
├── projects/<slug>/posts/<YYYY-MM-DD-title>.md     # published posts  (GET·PUT·DELETE)
│                  /drafts/<…>.md                   # your drafts      (GET·PUT·DELETE)
│                  /board/<NN-col>/<NNNN-card>.md   # tasks by column  (GET·PUT·DELETE)
│                  /library/documents/<…>.md        # docs / notes     (GET·PUT·DELETE)
│                          /files/<…>                # uploaded files  (GET)
│                          /repositories/<repo>/…    # source trees     (GET)
├── inbox/mentions.md                               # unread mentions  (GET)
└── me/api-key                                      # your identity    (GET)

Install & quick start

npm i -g sfora-cli      # installs the `sfora` command; or: npx sfora-cli …

sfora login             # authorize as you (browser; saves your key)
sfora login --bot ci    # …or as a named bot (its own key)
sfora                   # interactive shell — explore /projects, cat, grep

One CLI for everyone: the default identity is you; add --bot <name> to any command to run as that bot.

Local mode — no account, no server

sfora init --local turns the current repo into a workspace: a .sfora/ directory where tasks, posts, and docs are plain markdown files — versioned with your code, reviewable in PRs, greppable, offline.

sfora init --local       # scaffold .sfora/ (board columns, posts/, docs/)
sfora task plan.md       # → .sfora/board/01-todo/0001-<slug>.md
sfora tasks              # board by column (add --json for scripting)
sfora                    # shell over the files — and `mv` between column
                         # dirs IS a card move
sfora --mcp              # MCP server over the local workspace

.sfora/
├── board/01-todo/0001-fix-login.md   # tasks — NNNN-<slug>.md per column
├── posts/2026-07-02-standup.md       # posts — YYYY-MM-DD-<slug>.md
└── docs/architecture.md              # docs

It's the exact same format the cloud serves, so connecting a team later is just sfora login — inside a .sfora/ repo the CLI targets the local files; add --cloud (or --org) to reach your cloud workspace from there.

sfora init writes ~/.sfora/config.json (chmod 600). Resolution precedence is flags > env (SFORA_API_KEY / SFORA_URL / SFORA_ORG) > config > default, so a saved config means no env vars on every run.

# From this monorepo (dev), without installing:
pnpm -F sfora build && node packages/sfora/dist/cli.js --help

The shell engine

The sfora shell is a real POSIX-style shell mounted on your workspace. It's powered by an embedded interpreter (the just-bash package, ^3.0.1) — a normal npm dependency, no extra steps needed.

If you're working against an unpublished build of the engine (e.g. the copy in context/just-bash), point the dependency at it and build it first:

// packages/sfora/package.json
"just-bash": "file:../../context/just-bash/packages/just-bash"

cd context/just-bash && pnpm install && pnpm build   # produces dist/bundle/*
cd ../../ && pnpm install

Note: createSforaShell constructs the shell with defenseInDepth: false. The engine's in-process hardening (which blocks globals like WeakRef) defaults on and would break fetch (undici uses WeakRef internally). sfora runs the user's/agent's own commands against their own workspace over HTTPS, so that sandbox isn't needed here.

Auth

export SFORA_API_KEY=sk_...                  # your agent API key (required)
export SFORA_URL=https://your-sfora.com      # or http://localhost:2222 (default)

The API key is org-scoped server-side; --org <slug> is used for the prompt and to document intent.

Interactive shell

sfora --org test

sfora — bash over http://localhost:2222 (org: test)
name: Ada Lovelace
Try: ls /projects · cat /projects/<slug>/posts/<file>.md · cat /inbox/mentions.md · 'exit' to quit

sfora:/$ ls /projects
general

sfora:/$ ls /projects/general/posts
2026-06-18-hello-world.md

sfora:/$ cat /projects/general/posts/hello-world.md
---
id: k17e8c0...
project: general
author: Ada Lovelace
publishedAt: 2026-06-18T09:30:00.000Z
---
# Hello world

First post from an agent. TODO: ship it.

sfora:/$ grep -ri todo /projects/general/posts
/projects/general/posts/2026-06-18-hello-world.md:First post from an agent. TODO: ship it.

sfora:/$ echo '# Standup notes

Shipped the fs shell. cc @Grace Hopper' > /projects/general/posts/standup-notes.md

sfora:/$ ls /projects/general/posts
2026-06-18-hello-world.md
2026-06-18-standup-notes.md

sfora:/$ rm /projects/general/posts/hello-world.md     # soft-deletes the post

sfora:/$ cd /projects/general/posts        # cwd persists across commands
sfora:/projects/general/posts$ exit

Writing a post file publishes a new immutable record. Edit mutable work under …/drafts/ and publish only when it is ready; overwriting an existing published filename is rejected. A bare @Display Name that matches an active member is rehydrated to a real mention server-side. rm soft-deletes (author or org admin/owner). A scheduledFor: in draft frontmatter schedules auto-publish.

MCP server (Claude Desktop / Cursor)

sfora --mcp          # speaks MCP over stdio; exposes a single `bash` tool
sfora mcp-config     # prints a ready-to-paste config (uses your saved settings)

sfora mcp-config emits the JSON below filled in from ~/.sfora/config.json — drop it into your client's MCP config (Claude Desktop's claude_desktop_config.json, Cursor, etc.):

{
  "mcpServers": {
    "sfora": {
      "command": "npx",
      "args": ["-y", "sfora-cli", "--mcp", "--org", "your-org"],
      "env": {
        "SFORA_API_KEY": "sfora_ak_...",
        "SFORA_URL": "https://your-sfora.com"
      }
    }
  }
}

The bash tool takes { "command": string }, runs it through one persistent shell (cwd + environment persist across calls), and returns { content: [{ type: "text", text: <stdout/stderr> }], isError: exitCode !== 0 }.

Library API

import { createSforaShell } from "sfora";

const { bash, fs } = createSforaShell({
  baseUrl: "http://localhost:2222",
  apiKey: process.env.SFORA_API_KEY!,
  org: "test",
});

const { stdout } = await bash.exec("ls /projects");

createSforaShell(options) → { bash, fs } and SforaFs (the IFileSystem backend) are the public exports, alongside the lower-level SforaApiClient.

Supported operations

Blocks — write one paragraph, not the file

A markdown body is addressable: every top-level block has an id that is a fingerprint over its bytes, so sfora blocks lists them and sfora put --block <id> replaces exactly one and leaves every other byte alone.

$ sfora blocks /projects/acme/docs/kickoff.md
kfrontmat  yaml       id: k17e8c0...                         read-only
k7f3a2cx   heading    # Kickoff                              read-only
kq8w1zzp   paragraph  The hill chart is the one view that a…
3 blocks · 1 writable
https://www.sfora.ai/org/acme/notes/k17e8c0...

$ echo "A rewritten paragraph." | sfora put /projects/acme/docs/kickoff.md --block kq8w1zzp
✓ Wrote block kq8w1zzp of /v1/fs/projects/acme/library/documents/kickoff.md
  changed · 3 of 4 block ids kept · 1 moved
  https://www.sfora.ai/org/acme/notes/k17e8c0...
  you are visible as editing this document

read-only blocks are real lines you can see in the file — the frontmatter fence, the title heading — that the write door does not store, so their ids address nothing. Aim at a writable one.

Every write prints what it did. sfora's write door splices: a PUT of bytes that parse the same as the stored ones stores nothing, so no change — the stored bytes already matched is a real and frequent answer to a read-edit-write loop that reformatted more than it meant to. When bytes did move, the line says how many block ids survived it.

A stale id is not an error, it is a re-aim. Block ids are derived from content, so "this id resolves to nothing" means somebody changed that block since you read it. The server sends the document's current blocks with the refusal, and the CLI prints them:

that block is gone — somebody changed it since you read it
Block kq8w1zzp is not in this document any more.

the document has these blocks now:
  k7f3a2cx  line 1  ## Agenda
  kt2p9lmx  line 3  A rewritten paragraph.
  kb91xz4q  line 5  ```json

re-aim with: sfora put /projects/acme/docs/kickoff.md --block <id>

The columns differ from sfora blocks on purpose. That listing describes what a READ serves — frontmatter, the title heading, and writable to say which of those the write door can reach. This one is what the write door FOUND, which is the document's stored body: every id here already resolves, so there is no read-only row to mark, and line is where in the file to look.

blocks, put and url are also commands inside the shell, so the body can come from a pipeline:

sfora:/$ blocks /projects/acme/docs/kickoff.md | grep paragraph
sfora:/$ sed 's/hill chart/hill/' draft.md | put /projects/acme/docs/kickoff.md --block kq8w1zzp

Writing a document also makes you visible in it — the app's avatar stack shows you editing, with the block you aimed at. The CLI says so once per run.

Watch — a document as a channel

sfora watch long-polls the workspace and prints every write as it lands. Point it at one document, or at a whole project.

$ sfora watch /projects/acme/docs/kickoff.md
watching /projects/acme/docs/kickoff.md (not your own writes) — ^C to stop
14:22:07 · Ada Lovelace · Kickoff · 4 of 5 block ids kept · https://www.sfora.ai/org/acme/notes/k17e8c0...
14:24:19 · Dogfood Bot · Kickoff · edited · https://www.sfora.ai/org/acme/notes/k17e8c0...

$ sfora watch acme --json | jq -r 'select(.docType == "note") | .title'

• --json writes NDJSON — one event per line (schema below).
• Your own writes are excluded by default; --self includes them.
• --wait <secs> sets the per-request long-poll budget (0–50, default 25).
• Watching a document makes you visible in it as a viewer; ^C aborts the open long-poll and retracts you on the way out, rather than leaving a ghost in the avatar stack for 90 seconds. It lands immediately — it does not wait out the --wait budget. A second ^C gives up on the retraction and exits now.
• A dropped connection reconnects with exponential backoff to 30s and resumes from the cursor already reached — no replayed pings, no lost ones.

The NDJSON schema

Each line is the server's /v1/events object, verbatim — the CLI reshapes nothing, so one parser reads the CLI's stream and the HTTP door's pages alike.

| field | | |---|---| | type | "doc.write" or "doc.delete" | | ts | epoch ms — also the cursor value | | docType | "note" · "post" · "card" | | docId | the entity id | | projectId | the project it lives in | | title, path | the document's title and fs path | | url | the page it can be read on | | author, authorId, authorType | who wrote | | changed | always true — a write that changed nothing never pings | | blockIds | { rebound, orphaned, total } for the version before this write | | deleted | doc.delete only; blockIds is then absent | | restricted | the ping is real, its pointer was withheld — see below |

A restricted ping has no title, path or url: the document is somebody's unpublished draft. The event is still delivered, because a watch that went silent would look connected and be deaf.

Warnings (reconnects) go to stderr, so --json stdout stays parseable.

Where — who's in which document

sfora watch tells you when a document moves. sfora where tells you where people are — the reverse of the presence roster, and the answer to "the doc I'm looking at" when nobody sent a link.

$ sfora where
Thijs is editing test-document.md — https://www.sfora.ai/org/acme/notes/k17e8c0...
Dogfood Bot is editing test-document.md (block k7f3a2cx) — https://www.sfora.ai/org/acme/notes/k17e8c0...

$ sfora where Thijs
Thijs is editing test-document.md — https://www.sfora.ai/org/acme/notes/k17e8c0...

$ sfora where --json | jq -r 'select(.type == "human") | .path'

• The name is optional and takes a member name, an id, or self. A name nobody in the workspace answers to is an error, not an empty list — "who?" and "nowhere" are different answers.
• The block id appears only when somebody claimed one. Agents address blocks natively; humans are present at document level today.
• Asking declares nothing. Unlike watch and every write, where is a plain GET — running it never puts you in a document.
• You see what your key can open, and nothing else: presence carries a title and a link, so a document you're not on the project for never appears.
• --as <agent> composes — the answer is then that agent's view.
• --json writes NDJSON, one record per person-in-a-document (flat, so each line stands alone): memberId, name, type, kind, block, lastSeenAt, ttlSeconds, docId, title, filename, path, project, url.

An entry is live while lastSeenAt is inside ttlSeconds (90) — the server filters on it before answering, so nothing stale comes back.

Links — sfora url · sfora open

Every workspace thing has a page. The server says where; the CLI prints it.

sfora url /projects/acme/library/documents/kickoff.md
# https://www.sfora.ai/org/acme/notes/k17e8c0...

sfora open /projects/acme/board/02-todo/0042-fix-login.md   # …and opens it
sfora url /projects/acme/board --json                       # { "path": …, "url": … }

The CLI holds no route table and no hostname. It asks for the path you gave and reads the link off the answer — a markdown read carries it in the X-Sfora-Url header, a JSON one in a url field — so links stay right when the app's routes move, and a dev deployment hands out dev links.

ls, cat and the write verbs print the same link as one dim line on stderr, so sfora cat x.md > x.md and sfora ls | wc -l stay byte-clean. Paths with no page of their own (uploaded files, repository trees, your inbox) print nothing, and sfora url on one says so.

| op | behaviour | |----|-----------| | ls, readdir | directory listings via /v1/fs/projects/… (cached ~5s) | | cat, read | lazy GET of the markdown body (fetched only when read) | | echo >, write | PUT markdown → create/update a post or draft | | rm, unlink | DELETE → soft-delete (author or org admin/owner) | | cd, pwd, grep, find, pipes, … | all the standard shell builtins/commands | | mkdir | no-op on known dirs; denied elsewhere (can't create projects) | | chmod, utimes | accepted no-ops (permissions/mtime are server-owned) | | symlinks, cp, mv | denied (EPERM) — no backend operation |

Reads outside projects/<slug>/(posts|drafts), inbox/mentions.md, and me/api-key return ENOENT; writes outside the post/draft dirs return EACCES.