duetfs
v0.1.0
Published
`duetfs` is the agent-facing CLI for Duet workspaces. It is a thin client over the Duet REST API: authentication, files, memory, and workspace provisioning all go through `ctl.duet.so/v1` or the configured test API. The CLI owns no server logic and does n
Readme
duetfs
duetfs is the agent-facing CLI for Duet workspaces. It is a thin client over
the Duet REST API: authentication, files, memory, and workspace provisioning all
go through ctl.duet.so/v1 or the configured test API. The CLI owns no server
logic and does not shell the agent.
Configuration lives in ~/.duet/config.json with mode 0600. It stores the API
key, the default workspace, and the API base URL. DUET_API_URL and --api-url
override the stored base URL for tests and local runs. API keys are never printed.
Addresses use the contract-owned workspace:/path grammar. After
duetfs workspace use <slug>, slash-prefixed paths such as /notes/today.md
resolve through that default workspace.
Run duetfs --help for the command surface. duetfs --version reports the
published artifact version. Every command supports stable --json output.
Sync (macOS)
duetfs sync mirrors every workspace you belong to into ~/duet/<workspace>
and keeps both sides live over stock Syncthing (the one transfer engine —
supervised, bridged, and orchestrated by this package; never forked). It is
macOS-only in this release.
duetfs sync install/uninstall— a per-user launchd LaunchAgent that runs the daemon at login (keep-alive); symmetric and idempotent.duetfs sync status [--json]— per-workspace state read from the daemon's snapshot: up to date / syncing / retired / conflicts.duetfs sync run <workspace> [dir]— one workspace, foreground, to convergence (the slice-21 one-shot).duetfs sync daemon— the long-running entrypoint launchd invokes; not run by hand.
The Syncthing binary is pinned and ships per-arch in exact-versioned
@duetso/syncthing-<os>-<arch> optionalDependencies, sha256-verified on
resolve. binary.ts is the single pin; bun run release:syncthing stages the
binaries into those packages and dry-run-packs them. DUET_SYNCTHING_BIN
overrides the resolver with a local binary for development. The full,
first-time-user guide (install, git discipline, conflicts, retirement) lives in
the docs "Sync to your Mac" page.
The daemon never exposes Syncthing's admin API (loopback only), and .git /
node_modules never mirror — git history travels via real remotes.
Exit Codes
| Code | Meaning | | ---- | ---------------------------------------------------------------------------------- | | 0 | Success | | 3 | Authentication failed or no stored login | | 4 | Insufficient scope; JSON errors include the required scope when the API returns it | | 5 | Not found | | 6 | Network error | | 64 | Usage error |
