devdrop docs

Quickstart

Create a workspace once, set the remote once, then use short commands every day.

devdrop init ~/projects --remote ssh://server/backups/devdrop
cd ~/projects
devdrop sync
devdrop edit
devdrop secret set API_KEY=xxx

~/projects
  .devdrop.toml
  api/
  web/
  tools/

.devdrop.toml:
  [remote]
  url = "ssh://server/backups/devdrop"
  auto_sync = true

The model

1. Config.devdrop.toml stores the remote, pins, and secret scope defaults.

2. Syncdevdrop sync pulls, indexes local changes, pushes, hydrates files, and writes conflicts.

3. RemoteUse a local path, file:// URL, or ssh://host/path backend.

4. Reviewdevdrop edit opens an overlay in $EDITOR, shows a diff, then accepts or rejects.

Config File

The remote no longer has to be passed to every command. Add it during init, with remote add, or by editing .devdrop.toml.

devdrop init ~/projects --remote ssh://server/backups/devdrop
devdrop remote add ssh://server/backups/devdrop
devdrop config set pins api/src,web/src
devdrop config set secrets.default.scope dev

[remote]
url = "ssh://server/backups/devdrop"
auto_sync = true

pins = ["api/src", "web/src"]

[secrets.default]
scope = "dev"
env_vars = ["API_KEY"]

Daily use

See the workspace

devdrop status shows local, ignored, remote-only, locked secret, conflict, repo, and remote state.

List with state

devdrop ls ~/projects/api prints entries as local, ignored, metadata-only, remote-only, or secret-locked.

Keep important files

devdrop pin path writes a local pin, and devdrop config set pins ... stores shared pins.

Useful commands

devdrop syncRun bidirectional sync using the configured remote.

devdrop remote add ssh://host/pathSet or replace the remote in .devdrop.toml.

devdrop ignored [path]Show files excluded by built-in rules or .devsyncignore.

devdrop repo-status [path]List Git branches, dirty state, ahead/behind counts, and stale-base warnings.

devdrop repo update [path]Run a safe git fetch --prune and fast-forward merge for the repo upstream.

devdrop history pathShow known versions for a file.

devdrop recover path [--hash hash]Restore the latest known file version or a specific content hash.

Sync between machines

devdrop sync now pulls remote changes, scans local files, pushes updates, and handles conflicts in one command.

# Machine A
devdrop init ~/projects --remote ssh://server/backups/devdrop
cd ~/projects
devdrop sync

# Machine B
devdrop init ~/projects --remote ssh://server/backups/devdrop
cd ~/projects
devdrop sync

# Local remotes still work
devdrop remote add /mnt/devdrop-remote
devdrop sync

If both machines edit the same file before syncing, devdrop keeps the local file and writes the remote version as name.conflict-remote-<id>.ext.

Secrets

Use key-value secrets for the common case. devdrop creates a local workspace key when DEVDROP_SECRET_KEY is not set.

devdrop secret set API_KEY=xxx
devdrop secret list
devdrop run --repo ~/projects/api -- printenv API_KEY

# File-based secrets still work
devdrop secret add ~/projects/api/.env --scope dev
devdrop secret lock ~/projects/api/.env --scope dev
devdrop secret unlock ~/projects/api/.env --scope dev

Edit And Review

devdrop edit wraps the overlay workflow: copy to an overlay, open $EDITOR, show a diff, then ask whether to accept the changes.

cd ~/projects/api
devdrop edit

# Lower-level commands are still available
devdrop agent create --repo ~/projects/api --write-scope 'src/**'
devdrop agent diff <agent-id>
devdrop agent accept <agent-id>

For machine-readable agent calls, use devdrop status --json, devdrop repo-status --json, and devdrop secret request.

Health checks

Run doctor when setup feels wrong, a remote is missing, auth/device state is unclear, or a tool dependency is not installed.

devdrop doctor ~/projects
devdrop conflicts ~/projects
devdrop conflicts resolve ~/projects/api/src/config.conflict-remote-123.ts --use conflict