> ## 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.

# Quick Start

> Get your first Cloudstic backup running in under 5 minutes

## Prerequisites

Before starting, make sure you have:

<CardGroup cols={2}>
  <Card title="Cloudstic Installed" icon="check">
    Follow the [installation guide](/installation) if you haven't already
  </Card>

  <Card title="Storage Location" icon="database">
    Choose where to store backups (local disk, S3, B2, or SFTP)
  </Card>
</CardGroup>

<Tip>
  This quick start uses local storage for simplicity. For cloud storage (S3, B2), see the configuration examples at the end.
</Tip>

## Your First Backup in 4 Steps

<Steps>
  <Step title="Initialize a Repository">
    Create an encrypted repository to store your backups. Cloudstic will prompt you to set a password:

    ```bash theme={null}
    cloudstic init
    ```

    <Accordion title="Command output">
      ```
      Enter new repository password: ********
      Confirm repository password: ********
      Created new encryption key slots.
      Repository initialized (encrypted: true).
      ```
    </Accordion>

    This creates a local repository at `./backup_store` with AES-256-GCM encryption enabled.

    <Note>
      **Recommended**: Add a recovery key during initialization for emergency access:

      ```bash theme={null}
      cloudstic init -add-recovery-key
      ```

      Write down the 24-word recovery phrase and store it safely!
    </Note>
  </Step>

  <Step title="Create Your First Backup">
    Back up a local directory (e.g., your `Documents` folder):

    ```bash theme={null}
    cloudstic backup -source local:~/Documents
    ```

    Cloudstic will:

    * Scan all files in the directory
    * Chunk and compress each file with zstd
    * Encrypt chunks with AES-256-GCM
    * Upload only new chunks (deduplication)
    * Create an immutable snapshot

    <Accordion title="Command output">
      ```
      Scanning source...
      Found 1,247 files (2.3 GiB)

      Uploading new chunks... ███████████████████ 100%

      Backup complete.
        Files backed up:     1,247
        New chunks:          3,891
        Bytes uploaded:      2.3 GiB
        Deduplication saved: 0 B (first backup)
        Snapshot hash:       abc123def456...
      ```
    </Accordion>

    <Tip>
      **Skip development artifacts** with exclude patterns:

      ```bash theme={null}
      cloudstic backup -source local:~/project \
        -exclude "node_modules/" -exclude ".git/" -exclude "*.log"
      ```
    </Tip>
  </Step>

  <Step title="List Your Snapshots">
    View all backups in your repository:

    ```bash theme={null}
    cloudstic list
    ```

    <Accordion title="Command output">
      ```
      +-----+---------------------+------------------+--------+---------+-------------+------+
      | SEQ | CREATED             | SNAPSHOT HASH    | SOURCE | ACCOUNT | PATH        | TAGS |
      +-----+---------------------+------------------+--------+---------+-------------+------+
      | 1   | 2025-03-03 10:30:45 | abc123def456...  | local  |         | ~/Documents |      |
      +-----+---------------------+------------------+--------+---------+-------------+------+
      ```
    </Accordion>
  </Step>

  <Step title="Restore Your Files">
    Restore the latest snapshot:

    ```bash theme={null}
    cloudstic restore
    ```

    By default, this creates `restore.zip` in the current directory.

    <Accordion title="Restore specific files or folders">
      ```bash theme={null}
      # Restore a single file
      cloudstic restore -path Documents/report.pdf

      # Restore an entire folder
      cloudstic restore -path Documents/Projects/

      # Restore to a custom location
      cloudstic restore -output /path/to/my-backup.zip

      # Restore directly to a directory
      cloudstic restore -format dir -output /path/to/restored-files
       
      # Restore a specific snapshot (not the latest)
      cloudstic restore abc123def456...
      ```
    </Accordion>
  </Step>
</Steps>

<Check>
  **Congratulations!** You've successfully created and restored your first encrypted backup.
</Check>

## Next: Run an Incremental Backup

Cloudstic's content-addressable storage makes incremental backups automatic. Just run the same backup command again:

```bash theme={null}
cloudstic backup -source local:~/Documents
```

Only changed files will be processed, and deduplication will skip chunks that already exist:

```
Backup complete.
  Files backed up:     1,250 (+3 new)
  New chunks:          18
  Bytes uploaded:      4.7 MiB
  Deduplication saved: 2.29 GiB ⚡
  Snapshot hash:       def789abc012...
```

<Note>
  **Deduplication works across all sources**: If you back up the same file from different locations (e.g., a file synced between your local drive and Google Drive), it's only stored once.
</Note>

## Preview Changes with Dry Run

Before creating a backup, preview what would be uploaded:

```bash theme={null}
cloudstic backup -source local:~/Documents -dry-run
```

<Accordion title="Dry run output">
  ```
  Scanning source...
  Found 1,250 files (2.31 GiB)

  Would upload:
    New files:      3
    Modified files: 2
    New chunks:     18
    Bytes:          4.7 MiB

  Dry run complete (no data written).
  ```
</Accordion>

## Back Up Cloud Drives

Cloudstic works seamlessly with Google Drive and OneDrive using built-in OAuth:

<Tabs>
  <Tab title="Google Drive">
    ### Back up your entire Google Drive

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

    On first run, your browser opens automatically for authorization. The token is cached locally for future backups.

    <Note>
      **`gdrive-changes` vs `gdrive`**:

      * **`gdrive-changes`** (recommended): Uses the Changes API for fast incremental backups
      * **`gdrive`**: Full scan of every file (use only for the first backup or to force a rescan)
    </Note>

    ### Back up a specific folder

    ```bash theme={null}
    cloudstic backup -source "gdrive-changes:/path/to/folder"
    ```

    ### Back up a Shared Drive

    ```bash theme={null}
    cloudstic backup -source "gdrive-changes://Shared Drive Name"
    ```
  </Tab>

  <Tab title="OneDrive">
    ### Back up your entire OneDrive

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

    On first run, your browser opens automatically for authorization. The token is cached locally for future backups.

    <Note>
      **`onedrive-changes` vs `onedrive`**:

      * **`onedrive-changes`** (recommended): Uses the Delta API for fast incremental backups
      * **`onedrive`**: Full scan of every file (use only for the first backup or to force a rescan)
    </Note>

    <Tip>
      OneDrive backups use built-in OAuth credentials. No Microsoft app registration required!
    </Tip>
  </Tab>
</Tabs>

## Use Cloud Storage Backends

Store your backups on cloud storage for durability and accessibility:

<Tabs>
  <Tab title="Amazon S3">
    ```bash theme={null}
    # Set credentials (or use AWS CLI profiles)
    export AWS_ACCESS_KEY_ID=your-access-key
    export AWS_SECRET_ACCESS_KEY=your-secret-key

    # Initialize repository in S3 bucket
    cloudstic init -store s3:my-backup-bucket

    # Create a backup
    cloudstic backup -store s3:my-backup-bucket \
      -source local:~/Documents
    ```

    <Accordion title="S3-Compatible Storage (R2, MinIO, Wasabi)">
      For S3-compatible services, specify a custom endpoint:

      ```bash theme={null}
      # Cloudflare R2
      cloudstic init -store s3:my-bucket \
        -s3-endpoint https://<account_id>.r2.cloudflarestorage.com \
        -s3-region auto

      # MinIO
      cloudstic init -store s3:my-bucket \
        -s3-endpoint https://minio.example.com \
        -s3-region us-east-1
      ```
    </Accordion>
  </Tab>

  <Tab title="Backblaze B2">
    ```bash theme={null}
    # Set B2 credentials
    export B2_KEY_ID=your-key-id
    export B2_APP_KEY=your-app-key

    # Initialize repository in B2 bucket
    cloudstic init -store b2:my-backup-bucket

    # Create a backup
    cloudstic backup -store b2:my-backup-bucket \
      -source local:~/Documents
    ```

    <Tip>
      Backblaze B2 is significantly cheaper than S3 for backup storage. Perfect for long-term retention.
    </Tip>
  </Tab>

  <Tab title="SFTP">
    ```bash theme={null}
    # Initialize repository on SFTP server
    cloudstic init \
      -store sftp://backup@myserver.com/backups/cloudstic \
      -store-sftp-key ~/.ssh/id_ed25519

    # Create a backup
    cloudstic backup \
      -store sftp://backup@myserver.com/backups/cloudstic \
      -store-sftp-key ~/.ssh/id_ed25519 \
      -source local:~/Documents
    ```

    <Note>
      SFTP supports password authentication (`-store-sftp-password`) or SSH key authentication (`-store-sftp-key`). If neither is provided, Cloudstic uses your `SSH_AUTH_SOCK` agent.
    </Note>
  </Tab>
</Tabs>

## Simplify with Profiles

Save your backup configuration once and reuse it:

```bash theme={null}
# Create a store
cloudstic store new -name my-s3 -uri s3:my-backup-bucket -s3-region us-east-1

# Create a profile
cloudstic profile new -name documents -source local:~/Documents -store-ref my-s3

# Now backups are one command
cloudstic backup -profile documents
```

<Tip>
  See the [Using Profiles](/guides/profiles) guide for the complete walkthrough, including store encryption, cloud auth, and multi-profile automation.
</Tip>

### Alternative: Environment Variables

You can also use environment variables instead of profiles:

```bash ~/.bashrc or ~/.zshrc theme={null}
# Storage configuration
export CLOUDSTIC_STORE=s3:my-backup-bucket
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

# Encryption
export CLOUDSTIC_PASSWORD="my secure passphrase"

# Default source
export CLOUDSTIC_SOURCE=local:~/Documents
```

Now commands become much simpler:

```bash theme={null}
# Just run:
cloudstic backup

# Instead of:
cloudstic backup -store s3:my-bucket \
  -source local:~/Documents \
  -password "..."
```

## Common Operations

<AccordionGroup>
  <Accordion title="Compare two snapshots" icon="code-compare">
    See what changed between backups:

    ```bash theme={null}
    cloudstic diff abc123def456... def789abc012...
    ```

    Or compare against the latest:

    ```bash theme={null}
    cloudstic diff abc123def456... latest
    ```
  </Accordion>

  <Accordion title="Browse snapshot contents" icon="folder-tree">
    List all files in a snapshot:

    ```bash theme={null}
    cloudstic ls

    # Or specify a snapshot
    cloudstic ls abc123def456...
    ```
  </Accordion>

  <Accordion title="Remove old snapshots" icon="trash">
    Delete a specific snapshot:

    ```bash theme={null}
    cloudstic forget abc123def456...
    ```

    Apply retention policies to automatically clean up old backups:

    ```bash theme={null}
    # Keep last 7 snapshots + 4 weekly + 12 monthly
    cloudstic forget -keep-last 7 -keep-weekly 4 -keep-monthly 12
    ```
  </Accordion>

  <Accordion title="Reclaim storage space" icon="broom">
    After forgetting snapshots, run prune to delete unreferenced chunks:

    ```bash theme={null}
    cloudstic prune
    ```

    Or combine forget and prune in one command:

    ```bash theme={null}
    cloudstic forget abc123def456... -prune
    ```
  </Accordion>

  <Accordion title="Verify repository integrity" icon="shield-check">
    Check the repository for corruption:

    ```bash theme={null}
    # Basic integrity check
    cloudstic check

    # Full byte-level verification (re-hashes all chunks)
    cloudstic check -read-data
    ```
  </Accordion>

  <Accordion title="Change repository password" icon="key">
    ```bash theme={null}
    cloudstic key passwd
    ```

    Or non-interactively:

    ```bash theme={null}
    cloudstic key passwd \
      -password "old passphrase" \
      -new-password "new passphrase"
    ```
  </Accordion>
</AccordionGroup>

## Automation Tips

<CardGroup cols={2}>
  <Card title="Cron Job" icon="clock">
    Schedule daily backups:

    ```bash theme={null}
    # Add to crontab (crontab -e)
    0 2 * * * /usr/local/bin/cloudstic backup
    ```
  </Card>

  <Card title="Platform Keys" icon="robot">
    Use hex keys instead of passwords for automation:

    ```bash theme={null}
    # Generate a 32-byte hex key
    KEY=$(openssl rand -hex 32)

    # Initialize with platform key
    cloudstic init -encryption-key $KEY

    # Store key securely (e.g., in CI secrets)
    export CLOUDSTIC_ENCRYPTION_KEY=$KEY
    ```
  </Card>
</CardGroup>

<Warning>
  **Never commit credentials to version control!** Use environment variables or secret management tools.
</Warning>

## What's Next?

<CardGroup cols={2}>
  <Card title="Using Profiles" icon="id-card" href="/guides/profiles">
    Save and reuse backup configurations with profiles, stores, and auth
  </Card>

  <Card title="Encryption Keys" icon="lock" href="/guides/encryption-keys">
    Learn about key slots, recovery keys, and security design
  </Card>

  <Card title="Automation" icon="robot" href="/guides/automation">
    Schedule automatic backups with cron and systemd
  </Card>

  <Card title="Retention Policies" icon="clock" href="/guides/retention-policies">
    Manage snapshot lifecycle and reclaim storage space
  </Card>
</CardGroup>

<Tip>
  **Need help?** Join the discussion at [github.com/cloudstic/cli/discussions](https://github.com/cloudstic/cli/discussions) or report issues at [github.com/cloudstic/cli/issues](https://github.com/cloudstic/cli/issues).
</Tip>