CLI local mode

Local mode keeps a workspace in a .sfora/ folder inside your repository. Tasks, posts and docs are plain Markdown files, in the same format the cloud workspace uses, so you version them with your code. It needs no account and no network.

Create a local workspace

In the folder you want it in, usually the root of a repository:

sfora init --local

It creates this, and running it again changes nothing that exists:

.sfora/
  README.md
  board/
    01-triage/
    02-todo/
    03-in-progress/
    04-done/
  posts/
  docs/

• board/ holds tasks, one file per card, named NNNN-<slug>.md. The four folders are the four stages; there are no others.
• posts/ holds posts, named YYYY-MM-DD-<slug>.md. Drafts go in drafts/, which the CLI creates on the first draft.
• docs/ holds documents, named <slug>.md.

Every file needs a title: an H1 (# Title) or a title: in the frontmatter. Card frontmatter takes status, priority, labels, assignees and due.

When the CLI uses it

The CLI looks for a .sfora/ folder in the current folder and in each folder above it. When it finds one, the commands below work on those files.

To reach your cloud workspace from inside the repository, add --cloud. Naming a cloud target with --org, --url, --key or --bot does the same.

sfora tasks --cloud web

--local does the opposite: it insists on the local workspace and stops with an error if there is none.

Commands that work locally

sfora init --local
sfora task fix-login.md
sfora task spike.md --column triage
sfora tasks

Without --column, a task file's frontmatter decides the stage: column: names one, and status: closed sends it to Done. A task file whose number: matches an existing card replaces that card, and moves it if the stage changed.

Any other workspace command, such as chat, ask or watch, stops with: "cloud command — run it with --cloud (after sfora login), or outside the .sfora/ repo".

login, init, contexts, mcp-config, desktop and the skills commands work the same inside a .sfora/ folder as anywhere else.

The local shell

sfora with no command opens a bash shell rooted at .sfora/. It works on the real files, so ls, grep, sed, echo > and mv all change what is on disk. Moving a card's file to another stage folder moves the card:

sfora:/$ ls /board/02-todo
0003-fix-login.md
sfora:/$ mv /board/02-todo/0003-fix-login.md /board/03-in-progress/

The shell can't reach outside .sfora/. Type help for the paths and exit to leave.

Older boards

If a .sfora/ board has columns from an older version, the CLI moves its cards onto the four stages the first time it opens it, and says how many it moved. A card from a column it doesn't recognize goes to To do and keeps the old column's name as a label.

Troubleshooting

"no .sfora/ workspace found"

You passed --local outside a local workspace. Run sfora init --local first, or cd into the repository.

A command reaches the local files when you meant the cloud

You are inside a .sfora/ repository. Add --cloud, or --org <slug>.

"Title is required"

The file has no H1 and no title: in its frontmatter. Add # Title as its first line.

Last updated on October 6, 2026