Withcode CLI

The Withcode CLI syncs a local folder of Markdown and media with a Withcode native content source. The client is publicly downloadable, but it does not grant access to Withcode. Every operation still requires a personal, revocable CLI token and authorization for the target project.

Withcode accounts and native-source descriptors are issued to invited users.

0.2.4 sync fix

This release fixes accidental deletion of server-created task outcomes and plans during sync. Canonical files under .withcode/tasks/outcomes/ and .withcode/tasks/plans/ now participate in scanning and watching. CLI state, logs, locks, and journals remain excluded.

Existing conflict copies now block automatic sync and direct pushes until explicitly resolved. Upgrading may reveal conflicts older clients missed. The release does not automatically reconcile those copies or restore deleted server records. Restart continuously running clients after upgrading.

Run a pinned version

Agents and unattended automation should always use an exact tested version:

npx @withcodedev/[email protected] --help
# or
bunx @withcodedev/[email protected] --help

Using an exact version prevents an automated agent from silently executing a newly published release.

Connect a folder

Node 20 or newer is supported. Create a CLI token in Withcode Settings and copy the native source's descriptor URL. For an existing remote, use the safe clone flow:

npx @withcodedev/[email protected] auth set https://withcode.dev --token "$WITHCODE_CLI_TOKEN"
npx @withcodedev/[email protected] clone \
  https://withcode.dev/api/native-sources/123/descriptor calendar-folder

clone configures the folder and pulls when the source already contains files. For a new empty source it prints the explicit one-time push --initial command instead of importing automatically. Inspect any folder before writing:

cd calendar-folder
npx @withcodedev/[email protected] doctor
npx @withcodedev/[email protected] status
npx @withcodedev/[email protected] diff
npx @withcodedev/[email protected] pull
npx @withcodedev/[email protected] push

Run remote ls to inspect the configured remotes. The CLI stores authentication under ~/.withcode and per-folder sync state under .withcode/. Authentication files are written with user-only permissions.

Pull manifests are paginated against a stable server snapshot, so large sources do not require one unbounded response. The hosted service also applies request, payload, path, storage, and active-batch limits; a 429 response includes a retry interval.

For continuous synchronization, run a pinned current client as a foreground process rather than scheduling repeated one-shot pulls:

npx @withcodedev/[email protected] sync origin
# or synchronize every registered working tree
npx @withcodedev/[email protected] sync --all

Continuous sync uses a WebSocket change channel and source sequence cursors. Once its authoritative cursor is connected, an idle client does not poll the Withcode database. Explicit pull, status, and repeatedly launched sync commands remain one-shot operations and contact the service when invoked. The client sends jittered WebSocket protocol ping frames to detect half-open connections. Cloudflare answers these control frames without waking the source Durable Object; each actual connection or reconnection still authenticates and reads the canonical source cursor from the database.

Bot access

Prefer one scoped delegated token per bot or integration, minted from the human owner's Settings → CLI Access page. Select only the native-source projects that bot may use, then choose read only or read and write. Do not create a dedicated Withcode account just to isolate a bot.

The token secret stays the same when you edit grants. Adding a project authorizes that existing secret on the next request. The CLI still needs a separate remote/descriptor URL for each native source it syncs.

A project grant covers every native source in that project. It never creates projects, manages members, or grants account administration. New projects stay denied until you add them to the token.

Runtime dependencies and images

The package includes a small WebSocket client so event-driven sync also works on supported Node 20 installations without a global WebSocket. Image thumbnail generation additionally uses sharp, which is an optional peer:

npm install [email protected]

The CLI does not include the Withcode site, server, content, or credentials.

License and service terms

The CLI code is available under the MIT License. This license applies to the CLI software only; it does not grant access to the hosted Withcode service, accounts, projects, or content.

Using the hosted service requires an authorized Withcode account and is governed by the Terms of Service and Privacy Policy. CLI operations read local files and may transmit selected content to the Withcode host configured by the user.

Security

Keep CLI tokens out of source control, logs, and shared shell history. If you received access by invitation, report security issues privately through the same invitation channel. Do not include tokens or private content in a public report.