mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-11-03 13:55:30 -05:00
Jamie Pine
2d380fd264
Replaces the Mintlify setup (mint.json, docs.json, snippets) with a standalone Fumadocs app in docs/: Next.js app router, meta.json nav per section, its own bun install. Run with `just dev-docs`. Content pass alongside the migration: core architecture, data model, CLI, and networking pages rewritten around the daemon/source-store/ library split, new product-direction.mdx defining the product boundary, new drive-catalog plan, and the physical-drives plan updated to reference it. Whitepaper page retired.
173 lines
4.2 KiB
Plaintext
173 lines
4.2 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
|
|
~~~
|
|
|
|
## 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.
|
|
|
|
## 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.
|