Command line

Every command accepts the global options -C <dir> (run as if started in <dir>), --json (machine-readable output), -v (verbose) and -q (quiet). Commands find the project by looking for .devsync.toml in the current directory and its parents.

devsync

Edit locally, run remotely. Sync and remote execution built for flaky connections.

Usage: devsync [OPTIONS] <COMMAND>

Commands:
  init         Create .devsync.toml in the current directory
  push         Make the remote tree match the local one
  watch        Push on every save; collect results of running jobs. Keeps working offline
  exec         Sync, run a command remotely, show its output, pull back changed files [alias: run]
  submit       Sync and start a command remotely without waiting; prints the job id [alias: bg]
  logs         Show a job's output (default: the latest job), following it while it runs
  jobs         List jobs
  kill         Stop a running job (default: the latest)
  collect      Fetch output of running jobs into .devsync/jobs/ once, then exit
  pull         Get code from the remote: the whole project, or specific files/folders
  ls           List files on the remote and how they compare with yours
  cat          Print the remote version of a file (for diffs). Exits 1 if the remote doesn't have it [alias: show]
  git          Run git in the remote project, as if you were there
  tree         Browse the remote project one folder at a time: sizes, file counts and what is synced. Nothing is hashed; huge folders show lower bounds
  select       Choose what to sync: add files or folders to the selection
  unselect     Stop syncing files or folders (they stay untouched on the remote)
  status       Configuration, connectivity and pending changes
  changes      Local changes not yet on the remote, like `git status` (no network)
  doctor       Check the whole setup end to end and explain problems
  forward      Forward remote ports to localhost (reconnects automatically)
  shell        Interactive shell in the matching remote directory
  setup        Install coding-agent integration
  completions  Print shell completions
  help         Print this message or the help of the given subcommand(s)

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help
  -V, --version    Print version

Start with: devsync init user@host:~/project   then: devsync exec -- <command>

devsync init

Create .devsync.toml in the current directory

Usage: devsync init [OPTIONS] <TARGET>

Arguments:
  <TARGET>  user@host:/remote/path (or local:/path for a local agent)

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --force      Overwrite an existing config
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync push

Make the remote tree match the local one

Usage: devsync push [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
  -n, --dry-run    Show what would change without transferring
      --force      Allow deleting more than sync.max_delete remote files
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync watch

Push on every save; collect results of running jobs. Keeps working offline

Usage: devsync watch [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync exec

Sync, run a command remotely, show its output, pull back changed files

Usage: devsync exec [OPTIONS] <COMMAND>...

Arguments:
  <COMMAND>...  Command (use `--` before it if it has flags)

Options:
  -C, --dir <DIR>     Run as if started in this directory
      --no-push       Skip the sync before running
      --json          Machine-readable output (NDJSON events / JSON results)
      --no-pull-back  Do not bring back files the command changed
  -v, --verbose       Show every file transferred and connection details
  -q, --quiet         Only errors and warnings
  -h, --help          Print help

devsync submit

Sync and start a command remotely without waiting; prints the job id

Usage: devsync submit [OPTIONS] <COMMAND>...

Arguments:
  <COMMAND>...

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --no-push
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync logs

Show a job's output (default: the latest job), following it while it runs

Usage: devsync logs [OPTIONS] [ID]

Arguments:
  [ID]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --no-follow  Print what has been collected so far and exit
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync jobs

List jobs

Usage: devsync jobs [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --remote     Ask the remote instead of the local results folder
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync kill

Stop a running job (default: the latest)

Usage: devsync kill [OPTIONS] [ID]

Arguments:
  [ID]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync collect

Fetch output of running jobs into .devsync/jobs/ once, then exit

Usage: devsync collect [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync pull

Get code from the remote: the whole project, or specific files/folders.

Files that are new on the remote, or that you haven't edited since the last sync, are updated. Files you edited keep your version and the remote one is saved as <file>.devsync-remote (use --force to overwrite instead). Without paths the whole project is pulled and sync excludes apply; named paths are pulled even if excluded by `sync.ignore` or .gitignore. Built-in excludes (.git, node_modules, .venv, caches) and .devsyncignore always apply.

Examples: `devsync pull`, `devsync pull src/api tests/test_api.py`, `devsync pull results/ --to ~/Downloads`.

Usage: devsync pull [OPTIONS] [PATHS]...

Arguments:
  [PATHS]...
          Remote files or directories, relative to the project (omit for everything)

Options:
  -C, --dir <DIR>
          Run as if started in this directory

      --force
          Overwrite local edits with the remote version

      --json
          Machine-readable output (NDJSON events / JSON results)

      --to <DIR>
          Copy the paths into another local directory instead (exact copy)

  -n, --dry-run
          Show what would change without downloading

  -v, --verbose
          Show every file transferred and connection details

  -q, --quiet
          Only errors and warnings

  -h, --help
          Print help (see a summary with '-h')

devsync ls

List files on the remote and how they compare with yours.

Markers: + only on the remote, ~ changed on the remote, ! changed on both sides, = identical.

Usage: devsync ls [OPTIONS] [PATHS]...

Arguments:
  [PATHS]...
          Only under these remote paths

Options:
  -c, --changed
          Only files that differ from your copy (+, ~, !)

  -C, --dir <DIR>
          Run as if started in this directory

  -a, --all
          Include paths excluded by `sync.ignore` / .gitignore (built-in excludes and .devsyncignore always apply)

      --json
          Machine-readable output (NDJSON events / JSON results)

  -v, --verbose
          Show every file transferred and connection details

  -q, --quiet
          Only errors and warnings

  -h, --help
          Print help (see a summary with '-h')

devsync tree

Browse the remote project one folder at a time: sizes, file counts and what is synced. Nothing is hashed; huge folders show lower bounds

Usage: devsync tree [OPTIONS] [PATH]

Arguments:
  [PATH]  Remote folder, relative to the project (default: the project root)

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync select

Choose what to sync: add files or folders to the selection.

Without arguments, shows the current selection. Unselected paths are neither scanned nor synced, and stay untouched on the remote.

Usage: devsync select [OPTIONS] [PATHS]...

Arguments:
  [PATHS]...


Options:
  -C, --dir <DIR>
          Run as if started in this directory

      --pull
          Download the selected paths right away

      --all
          Go back to syncing everything

      --json
          Machine-readable output (NDJSON events / JSON results)

  -v, --verbose
          Show every file transferred and connection details

  -q, --quiet
          Only errors and warnings

  -h, --help
          Print help (see a summary with '-h')

devsync unselect

Stop syncing files or folders (they stay untouched on the remote)

Usage: devsync unselect [OPTIONS] <PATHS>...

Arguments:
  <PATHS>...

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync status

Configuration, connectivity and pending changes

Usage: devsync status [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync changes

Local changes not yet on the remote, like `git status` (no network)

Usage: devsync changes [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync doctor

Check the whole setup end to end and explain problems

Usage: devsync doctor [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync forward

Forward remote ports to localhost (reconnects automatically)

Usage: devsync forward [OPTIONS] [PORTS]...

Arguments:
  [PORTS]...  Ports (default: exec.ports from the config)

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync shell

Interactive shell in the matching remote directory

Usage: devsync shell [OPTIONS]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help

devsync setup

Install coding-agent integration

Usage: devsync setup [OPTIONS] <WHAT>

Arguments:
  <WHAT>
          Possible values:
          - claude:    Claude Code hook + CLAUDE.md instructions
          - agents-md: AGENTS.md instructions (Codex, Cursor, others)
          - all:       Everything above

Options:
  -C, --dir <DIR>
          Run as if started in this directory

      --json
          Machine-readable output (NDJSON events / JSON results)

  -v, --verbose
          Show every file transferred and connection details

  -q, --quiet
          Only errors and warnings

  -h, --help
          Print help (see a summary with '-h')

devsync completions

Print shell completions

Usage: devsync completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>  [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -C, --dir <DIR>  Run as if started in this directory
      --json       Machine-readable output (NDJSON events / JSON results)
  -v, --verbose    Show every file transferred and connection details
  -q, --quiet      Only errors and warnings
  -h, --help       Print help