---
title: "CLI local mode: Markdown in your repo"
description: "Keep tasks, posts and docs as plain Markdown files in a .sfora/ folder in your repository, with no account and no server."
canonical: "https://www.sfora.ai/docs/developers/cli/local"
---
# CLI local mode: Markdown in your repo

> Keep tasks, posts and docs as plain Markdown files in a .sfora/ folder in your repository, with no account and no server.

Source: https://www.sfora.ai/docs/developers/cli/local

**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:

```bash
sfora init --local
```

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

```text
.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.

```bash
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

| Command | Locally |
|---|---|
| `sfora task <file.md>` | Adds a card to **To do**, numbered after the highest card on the board. `--column` picks another stage. |
| `sfora post <file.md>` | Adds a post, named by today's date and its title. `--draft` puts it in `drafts/`. |
| `sfora doc <file.md>` | Adds a document to `docs/`. |
| `sfora tasks` | Lists the board, stage by stage. `--column` lists one stage. |
| `sfora posts` | Lists the posts. `--draft` lists the drafts. |
| `sfora ls [path]` | Lists a folder. Without a path, it lists the workspace root. |
| `sfora cat <path>` | Prints a file. |
| `sfora me` | Says you are in a local workspace, and where. `sfora whoami` is the same. |
| `sfora` | Opens the shell over the local files. |
| `sfora --mcp` | Serves the local workspace as an MCP server. |

```bash
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:

```bash
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.

Related: https://www.sfora.ai/docs/developers/cli/commands, https://www.sfora.ai/docs/developers/cli/shell, https://www.sfora.ai/docs/developers/mcp
