mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-11-02 13:25:19 -05:00
Jamie Pine
bcc7337b0d
Every job that changes the filesystem records effects (created, moved, trashed with where it went, replaced with where the previous bytes went, removed, attributes before and after) in a job_journal table through ctx.record. The trash reports locations: NSFileManager on macOS, the trash crate's listing elsewhere, and a .spacedrive/trash/<job>/ directory on volumes with none. Overwrites in copy, merge and extract stash the previous file there. files.undo previews the reverse as an FsPlan, refuses what changed since, and its job writes its own journal. Also: files.rename on preflight with per-filesystem name rules and case probing, files.rename_batch with ordered rules and a job that never overwrites; remove_extras on files.merge for a mirror; files.organize and files.flatten as in-place renames; files.archive and files.extract for zip and tar.zst, planned from the archive's directory; files.set_attributes and files.link; files.trash_list and files.trash_empty; jobs.journal and a journal summary on jobs.list. The copy job now honors the skip policy and merges a folder onto an existing folder instead of overwriting inside it, and the copy preview plans a keep-both copy at its numbered name. 30 tests over the fixture. Docs, the plan's status table and PROJECT_STATUS updated.
273 lines
8.4 KiB
Plaintext
273 lines
8.4 KiB
Plaintext
---
|
|
title: Spacedrive CLI
|
|
description: Operate the Spacedrive daemon from a terminal or script
|
|
sidebarTitle: Overview
|
|
---
|
|
|
|
The Spacedrive CLI is a typed client of the same daemon used by the desktop and
|
|
web interfaces. It can manage libraries, sources, files, jobs, devices, logs,
|
|
and remote operations without bypassing core permissions or durability rules.
|
|
|
|
## Install from source
|
|
|
|
~~~bash
|
|
cargo build --release --bin sd-cli --bin sd-daemon
|
|
~~~
|
|
|
|
The binaries are written to **target/release**. Keep **sd-cli** and
|
|
**sd-daemon** together if you use daemon auto-start.
|
|
|
|
## Start the daemon
|
|
|
|
~~~bash
|
|
sd-cli start
|
|
sd-cli status
|
|
sd-cli stop
|
|
~~~
|
|
|
|
Run the daemon in the foreground while diagnosing startup:
|
|
|
|
~~~bash
|
|
sd-cli start --foreground
|
|
~~~
|
|
|
|
The desktop app starts automatic discovery once its window shows, which tracks
|
|
the system volume, adds the home folder as a source and maps every attached
|
|
drive. From a terminal, request the same pass:
|
|
|
|
~~~bash
|
|
sd-cli index start --defaults
|
|
~~~
|
|
|
|
For a library that should hold only what you add to it, such as one whose data
|
|
directory lives on an external drive, start the daemon without those defaults.
|
|
The pass still restores, heals and hashes the sources you added:
|
|
|
|
~~~bash
|
|
sd-cli --data-dir "/Volumes/Archive/.spacedrive" start --no-default-sources
|
|
~~~
|
|
|
|
`restart` takes the same flag.
|
|
|
|
## Select a library
|
|
|
|
~~~bash
|
|
sd-cli library create Personal
|
|
sd-cli library list
|
|
sd-cli library switch --library-id <LIBRARY_ID>
|
|
sd-cli library info
|
|
~~~
|
|
|
|
The selected library is remembered for later commands. Use **--library** where
|
|
a command supports an explicit library override.
|
|
|
|
## Track and preserve sources
|
|
|
|
~~~bash
|
|
sd-cli sources track ~/Documents
|
|
sd-cli sources track /Volumes/Archive --unfiltered
|
|
sd-cli sources list
|
|
sd-cli sources update <SOURCE_ID> --name "Archive 2026"
|
|
sd-cli sources verify <SOURCE_ID>
|
|
sd-cli sources freeze <SOURCE_ID>
|
|
~~~
|
|
|
|
A source owns capture and its portable store. Locations are named pins inside a
|
|
source. There are no shallow, content, or deep location index modes.
|
|
|
|
## Inspect durable work
|
|
|
|
~~~bash
|
|
sd-cli job list
|
|
sd-cli job info <JOB_ID>
|
|
sd-cli job monitor --job-id <JOB_ID>
|
|
sd-cli job pause <JOB_ID>
|
|
sd-cli job resume <JOB_ID>
|
|
sd-cli job cancel <JOB_ID>
|
|
~~~
|
|
|
|
Not every job can resume safely. A filesystem walk starts fresh after process
|
|
loss because its sweep evidence is process-local. Transfer and analysis jobs
|
|
resume only when their implementation preserves enough state.
|
|
|
|
## Read logs
|
|
|
|
~~~bash
|
|
sd-cli logs show --timestamps
|
|
sd-cli logs show --job-id <JOB_ID>
|
|
sd-cli logs follow --timestamps --show-job-id
|
|
~~~
|
|
|
|
Logs carry job and library context when the daemon has it. Machine-readable
|
|
operation output is separate from diagnostic logging.
|
|
|
|
## Pair devices
|
|
|
|
~~~bash
|
|
sd-cli network pair generate
|
|
sd-cli network pair join "<PAIRING_CODE>"
|
|
sd-cli network pair status
|
|
sd-cli devices list
|
|
~~~
|
|
|
|
Pairing establishes device identity. Library, source, subtree, and operation
|
|
grants still control what the peer can access.
|
|
|
|
## File and search operations
|
|
|
|
Explore each domain from the installed binary:
|
|
|
|
~~~bash
|
|
sd-cli file --help
|
|
sd-cli search --help
|
|
sd-cli tag --help
|
|
sd-cli redundancy --help
|
|
sd-cli volume --help
|
|
~~~
|
|
|
|
Use Spacedrive paths when a command needs an address. The same operation can
|
|
route to local files, remote sources, provider objects, or content identity.
|
|
|
|
Compare two indexed folders without reading either drive. The first folder is
|
|
A and the second is B. By path, files pair by their path within each folder. By
|
|
content, a file matches wherever its bytes sit in the other folder, which is
|
|
how to check a backup:
|
|
|
|
~~~bash
|
|
sd-cli file compare ~/Photos /Volumes/Backup/Photos --show different
|
|
sd-cli file compare ~/Photos /Volumes/Backup/Photos --by content --show only-a
|
|
~~~
|
|
|
|
Delete from a folder what a comparison names, here the files the backup
|
|
already holds. The job reads both copies in full before it removes one:
|
|
|
|
~~~bash
|
|
sd-cli file delete ~/Photos --against /Volumes/Backup/Photos --by content --show both
|
|
~~~
|
|
|
|
Copy, move, merge and delete all show their findings and their plan before
|
|
asking. Validation says whether the operation may run and how, the plan says
|
|
what would exist afterward, and the job applies the same decisions leaf by
|
|
leaf against the live filesystem. `--dry-run` stops after the plan:
|
|
|
|
~~~bash
|
|
sd-cli file copy ~/Photos/2024 --destination /Volumes/Backup/Photos --dry-run
|
|
sd-cli file copy ~/Photos/2024 --destination /Volumes/Backup/Photos --move-files
|
|
sd-cli file merge /Volumes/Expansion/Photos --into /Volumes/NAS/Photos --dry-run
|
|
sd-cli file merge /Volumes/Expansion/Photos --into /Volumes/NAS/Photos --on-conflict keep-both --consume
|
|
~~~
|
|
|
|
A delete's plan says which of the files are the last copy of their content
|
|
anywhere in the library, before anything is removed. Dedupe keeps one copy of
|
|
each duplicated content and removes the rest, or the copies you name, after
|
|
reading each pair in full:
|
|
|
|
~~~bash
|
|
sd-cli file dedupe ~/Photos --dry-run
|
|
sd-cli file dedupe --keep ~/Photos/2024/IMG_0041.JPG
|
|
sd-cli file dedupe ~/Downloads --keep-under /Volumes/NAS/Photos
|
|
~~~
|
|
|
|
Rename one path, or many by rules applied to each name in order. Validation
|
|
resolves every new name against the directory and the volume's filesystem, so
|
|
a name NTFS refuses, a name already there, or two files wanting one name is a
|
|
finding before anything moves, and the plan lists each old name beside its
|
|
new one:
|
|
|
|
~~~bash
|
|
sd-cli file rename ~/Photos/2024/IMG_0041.JPG --to "beach.jpg"
|
|
sd-cli file rename ~/Photos/2024/*.JPG --sequence "Trip_{n:03}" --lower-extension --dry-run
|
|
sd-cli file rename ~/Photos/2024/*.JPG --template "{captured:%Y-%m-%d} {name}{ext}"
|
|
~~~
|
|
|
|
Every job that changes the filesystem writes a journal of what it did, and
|
|
undo reverses it from the journal, newest effect first, after showing the
|
|
plan and refusing whatever changed since. A merge with `--remove-extras` is
|
|
a mirror: the destination ends up matching the sources, with the files it
|
|
alone held moved to the trash. The trash lists what Spacedrive put there
|
|
and puts it back through undo:
|
|
|
|
~~~bash
|
|
sd-cli job journal 4f2c…
|
|
sd-cli file undo 4f2c… --dry-run
|
|
sd-cli file merge ~/Projects --into /Volumes/NAS/Projects --on-conflict keep-newer --remove-extras
|
|
sd-cli file trash list
|
|
sd-cli file trash restore 4f2c… 3
|
|
sd-cli file trash empty
|
|
~~~
|
|
|
|
Organize a folder into subfolders by date, kind or extension, or flatten
|
|
one; write an archive or extract one; set attributes; make a link. Each
|
|
shows its plan first:
|
|
|
|
~~~bash
|
|
sd-cli file organize ~/Downloads --by kind --dry-run
|
|
sd-cli file organize ~/Photos/2024 --by date --field captured --granularity year-month --recursive
|
|
sd-cli file flatten ~/Downloads/unpacked --on-conflict keep-both
|
|
sd-cli file archive ~/Projects/site --to ~/Archive/site.tar.zst --remove-sources
|
|
sd-cli file extract ~/Downloads/kit.zip --to ~/Downloads/kit --strip-components 1
|
|
sd-cli file attributes ~/Scripts/*.sh --mode 755
|
|
sd-cli file link ~/Desktop/Photos --target ~/Pictures/Photos
|
|
~~~
|
|
|
|
## Structured output
|
|
|
|
Pass **--format json** before the command to receive structured output:
|
|
|
|
~~~bash
|
|
sd-cli --format json sources list
|
|
sd-cli --format json job list
|
|
~~~
|
|
|
|
Scripts should prefer JSON and stable IDs over parsing human tables.
|
|
|
|
## Call any registered operation
|
|
|
|
The generic passthrough exposes the operation registry:
|
|
|
|
~~~bash
|
|
sd-cli op sources.list --json '{}'
|
|
sd-cli op tags.create --library <LIBRARY_ID> --json '{"name":"Keep"}'
|
|
~~~
|
|
|
|
Operation names and schemas are the contract. The CLI does not translate an
|
|
arbitrary model response into shell commands. Skills and MCP tools use this same
|
|
bounded surface.
|
|
|
|
## Multiple local instances
|
|
|
|
Use a named instance to run isolated daemon state on one machine:
|
|
|
|
~~~bash
|
|
sd-cli --instance lab start
|
|
sd-cli --instance lab status
|
|
~~~
|
|
|
|
An instance changes the data directory and socket identity. It does not create a
|
|
new security boundary from the operating-system account that runs it.
|
|
|
|
## Data directory
|
|
|
|
Override the default state directory explicitly:
|
|
|
|
~~~bash
|
|
sd-cli --data-dir /srv/spacedrive-data start
|
|
~~~
|
|
|
|
Use the same value for every command that addresses that daemon. Back up this
|
|
directory because it contains library state, source stores, assertions, and job
|
|
history that a filesystem scan may not recover.
|
|
|
|
## Discover commands
|
|
|
|
~~~bash
|
|
sd-cli --help
|
|
sd-cli sources --help
|
|
sd-cli network --help
|
|
sd-cli op --help
|
|
~~~
|
|
|
|
The installed help is authoritative for command spelling. See [Get
|
|
Started](/overview/get-started) for the first library flow and [API](/core/api)
|
|
for the operation contract behind the CLI.
|