> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cloudstic backup

> Create a new backup snapshot from a source

Create a new backup snapshot from a local filesystem, SFTP server, Google Drive, or OneDrive. Backups are deduplicated, compressed, and encrypted automatically.

## Usage

```bash theme={null}
cloudstic backup [options]
```

## Source Types

Cloudstic supports multiple backup sources:

* **local**: Local filesystem directory
* **sftp**: Remote directory via SFTP
* **gdrive**: Google Drive (full scan)
* **gdrive-changes**: Google Drive (incremental via changes API)
* **onedrive**: Microsoft OneDrive (full scan)
* **onedrive-changes**: Microsoft OneDrive (incremental via delta API)

## Options

<ParamField path="-profile" type="string" env="CLOUDSTIC_PROFILE">
  Run backup using a named profile from profiles.yaml. The profile's source, store, auth, tags, and exclude settings are applied automatically. CLI flags override profile values.
</ParamField>

<ParamField path="-all-profiles" type="boolean" default="false">
  Run backup for all enabled profiles from profiles.yaml. Each profile runs with its own store, source, and auth configuration. Mutually exclusive with `-profile`.
</ParamField>

<ParamField path="-source" type="string" default="gdrive">
  Source to backup from. Can also be set via `CLOUDSTIC_SOURCE` environment variable.

  For local and SFTP sources, include the path as a URI: `local:<path>` or `sftp://[user@]host[:port]/<path>`. For cloud sources, use keywords or keywords with paths: `gdrive[://<Drive Name>][/<path>]`, `gdrive-changes[://<Drive Name>][/<path>]`, `onedrive[://<Drive Name>][/<path>]`, `onedrive-changes[://<Drive Name>][/<path>]`.
</ParamField>

<ParamField path="-auth-ref" type="string">
  Use a named auth entry from profiles.yaml for cloud source credentials. Allows reusing OAuth tokens across commands without a full profile.
</ParamField>

<ParamField path="-tag" type="string" repeatable>
  Tag to apply to the snapshot. Can be specified multiple times to add multiple tags.

  Tags are useful for organizing and filtering snapshots later.
</ParamField>

<ParamField path="-exclude" type="string" repeatable>
  Exclude pattern using gitignore syntax. Can be specified multiple times.

  Examples: `*.log`, `node_modules/`, `.git/`
</ParamField>

<ParamField path="-exclude-file" type="string" default="">
  Path to a file containing exclude patterns (one per line, gitignore syntax).

  Patterns from this file are combined with patterns from `-exclude` flags.
</ParamField>

<ParamField path="-ignore-empty-snapshot" type="boolean" default="false">
  Skip creating a new snapshot when the resulting tree is identical to the previous snapshot.

  The backup still scans the source and reports stats, but no new checkpoint is written when nothing changed.
</ParamField>

<ParamField path="-dry-run" type="boolean" default="false">
  Scan the source and report changes without writing to the repository.

  Useful for testing exclude patterns or previewing what will be backed up.
</ParamField>

<ParamField path="-volume-uuid" type="string" default="">
  Override the auto-detected volume UUID for local sources. Enables cross-machine incremental backups for portable drives. Can also be set via `CLOUDSTIC_VOLUME_UUID` environment variable.

  On macOS and Linux, the GPT partition UUID is detected automatically and is stable across operating systems. Use this flag when auto-detection is unavailable (Windows, MBR-formatted drives) or to manually link backups to a specific snapshot lineage.
</ParamField>

### Global Options

Use `-json` to emit the command result as a single JSON document on stdout.

## Examples

<CodeGroup>
  ```bash Local Directory theme={null}
  cloudstic backup -source local:./documents
  ```

  ```bash With Tags theme={null}
  cloudstic backup -source local:./code -tag production -tag v1.0
  ```

  ```bash Google Drive theme={null}
  cloudstic backup -source gdrive
  ```

  ```bash Google Drive (Shared Drive) theme={null}
  cloudstic backup -source "gdrive://Company Data"
  ```

  ```bash With Exclusions theme={null}
  cloudstic backup -source local:. \
    -exclude "*.log" \
    -exclude "node_modules/" \
    -exclude ".git/"
  ```

  ```bash Using Exclude File theme={null}
  cloudstic backup -source local:. -exclude-file .cloudsticignore
  ```

  ```bash Dry Run theme={null}
  cloudstic backup -source local:./documents -dry-run
  ```

  ```bash Ignore Empty Snapshot theme={null}
  cloudstic backup -source local:./documents -ignore-empty-snapshot
  ```

  ```bash SFTP Source theme={null}
  cloudstic backup -source sftp://deploy@web.example.com/var/www/html
  ```

  ```bash OneDrive Incremental theme={null}
  cloudstic backup -source onedrive-changes
  ```

  ```bash Using a Profile theme={null}
  cloudstic backup -profile documents
  ```

  ```bash All Profiles theme={null}
  cloudstic backup -all-profiles
  ```

  ```bash Profile with Override theme={null}
  cloudstic backup -profile documents -source local:~/Downloads
  ```
</CodeGroup>

## Output

Successful backup output includes:

```plaintext theme={null}
Backup complete. Snapshot: snapshot/a3f8d2..., Root: node/b4e9c1...
Files:  5 new,  2 changed,  120 unmodified,  0 removed
Dirs:   1 new,  0 changed,  15 unmodified,  0 removed
Added to the repository: 2.4 MiB (1.8 MiB compressed)
Processed 142 entries in 8s
Snapshot a3f8d2... saved
```

## Incremental Backups

Cloudstic automatically performs incremental backups by comparing against the previous snapshot from the same source. Only new and changed files are uploaded to the repository.

For cloud sources (Google Drive, OneDrive), the `-changes` variants use the provider's native change tracking APIs for more efficient scans:

* `gdrive-changes` uses Google Drive Changes API
* `onedrive-changes` uses Microsoft Graph Delta API

<Note>
  The first backup from a source is always a full backup. Subsequent backups from the same source identity are incremental. Identity matching prefers stable IDs (`type + identity + path_id`) and falls back to legacy matching for older snapshots.
</Note>

<Note>
  For `gdrive-changes` and `onedrive-changes`, enabling `-ignore-empty-snapshot` means an unchanged run does not persist the fresh change token for that run. The next backup may therefore revisit the same empty delta window.
</Note>

## Exclude Patterns

Exclude patterns follow gitignore syntax:

* `*` matches any sequence of non-separator characters
* `**` matches any sequence of characters including path separators
* `?` matches any single non-separator character
* Patterns ending with `/` only match directories
* Patterns starting with `!` negate the pattern

<Tip>
  Create a `.cloudsticignore` file in your source directory to store exclude patterns, then use `-exclude-file .cloudsticignore` for cleaner commands.
</Tip>

## Source Authentication

### Local and SFTP

For SFTP sources, provide connection details via flags:

```bash theme={null}
cloudstic backup -source sftp://myuser@server.example.com/remote/path \
  -source-sftp-key ~/.ssh/id_rsa \
  -source-sftp-known-hosts ~/.ssh/known_hosts
```

| Flag                              | Description                         |
| --------------------------------- | ----------------------------------- |
| `-source-sftp-password <pw>`      | SFTP password                       |
| `-source-sftp-key <path>`         | Path to private key                 |
| `-source-sftp-known-hosts <path>` | Path to known\_hosts file           |
| `-source-sftp-insecure`           | Skip host key validation (INSECURE) |

### Google Drive

Google Drive sources use OAuth 2.0. On first use, Cloudstic will open a browser for authentication. The access token is cached as `google_token.json` in your [platform config directory](/installation#configuration-directory).

For service account authentication, set `GOOGLE_APPLICATION_CREDENTIALS` to point to your service account JSON key.

### OneDrive

OneDrive sources also use OAuth 2.0 with browser-based authentication. The token is cached as `onedrive_token.json` in your [platform config directory](/installation#configuration-directory).

For custom OAuth applications, set `ONEDRIVE_CLIENT_ID` with your registered app client ID.

## Performance

Backup performance depends on:

* **Source type**: Cloud sources (Drive/OneDrive) are slower than local/SFTP due to API rate limits
* **File size distribution**: Many small files take longer to process than fewer large files
* **Network bandwidth**: Upload speed to your storage backend
* **Deduplication**: Unchanged files are skipped instantly

<Tip>
  Use `-verbose` to see per-file progress. Use `-quiet` to suppress progress bars and only show the final summary.
</Tip>

## Error Handling

If the backup fails partway through:

* The snapshot is NOT saved: the repository remains in a consistent state
* No partial snapshots are created
* Data already uploaded (chunks, content) is safely deduplicated on the next run
* Simply re-run the backup command to retry

<Note>
  `backup` acquires a **shared lock** on the repository at run start (skipped for `-dry-run`). Multiple backups can run concurrently because shared locks coexist. The lock is released when the command exits. If the repository holds an exclusive lock (from a running `prune`), backup will fail immediately with a lock error. See [Repository Locking](/advanced/locking) for details.
</Note>

## See Also

* [cloudstic restore](/commands/restore): Restore files from a backup snapshot
* [cloudstic list](/commands/list): List all backup snapshots
* [cloudstic diff](/commands/diff): Compare two snapshots