Taskmark Cloud

What Cloud is for

Local Taskmark is the source of truth. Agents and developers write epics, stories, tasks, and bugs as files in the board repository. Taskmark Cloud exists so the rest of the team can open that board in a browser: follow delivery, presence, and work logs without cloning the repo or running the local UI.

Cloud is a published copy. Planning and implementation still happen locally with /tkmd-* commands. The hosted app does not invent work items; it shows the markdown your local process last pushed.

The hosted app is cloud.taskmark.dev.

Configuration guide

Each Cloud project has one board sync token. That token selects the destination project and authorizes uploads. You commit it on the local board as dotenv keys in a board-root .config file (not .env). Clones of the board start syncing as soon as someone runs the local UI.

1. Sign in at Taskmark Cloud and create or open a project.
2. Open Settings on that Cloud project and copy the board sync token (it starts with tmk_). Treat it like a password: anyone with the token can upload to the project.
3. In the local board root, set TASKMARK_SYNC_TOKEN=tmk_… in .config. You can copy .config.example if the board ships one. Commit .config so every clone uses the same project.
4. From that board folder run npx taskmark dev or npx taskmark serve. Keep the process running. The CLI watches board markdown and .config, then pushes changed files and a rebuilt snapshot.
5. Refresh the Cloud project board. After the first successful sync, local markdown edits keep the hosted board up to date.

# board-root .config
TASKMARK_SYNC_TOKEN=tmk_

Configuration reference

• TASKMARK_SYNC_TOKEN — the project token copied from Taskmark Cloud Settings. That is the only setting the board needs.

If .config has no valid token, TASKMARK_SYNC_TOKEN in the environment or a local .env is a fallback. Local UI no longer has a Settings tab for the token — edit .config.

Verify the connection

Keep the local command running and watch its terminal. A healthy first sync names the Cloud origin and project, counts local and changed files, builds the board snapshot, uploads one or more batches, and prints the resulting board version. Later markdown edits should normally report only the files that changed.

[taskmark sync] cloud https://cloud.taskmark.dev
[taskmark sync] My project (my-project) — 42 local file(s), 1 changed, 0 removed
[taskmark sync] building board snapshot
[taskmark sync] uploading 1 file(s)
[taskmark sync] done — board version 2

Troubleshooting

• Sync is not configured: check that .config is at the board root and the token begins with tmk_.
• Token rejected: copy the current token from Cloud Settings. If an owner rotated it, update every local clone.
• Wrong Cloud project: the token chooses the destination. Replace it with the token from the intended project.

What gets pushed

Sync uploads board markdown (epics, stories, tasks, bugs) and related board files, then a snapshot Cloud uses to render the same UI. The .config file itself is not sent as a board file, so the token is not echoed back through the snapshot.

Rotate the token in Cloud Settings if it leaks. Every local board must put the new value in .config before it can sync again.

Open the local board

Connecting Cloud does not replace the local board UI. After setup, run the CLI from the board folder as usual.

# inside a board folder
npx taskmark serve
npx taskmark dev

Next: Setup if you still need a local board, or Commands for the daily plan/do/commit loop.