> ## 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 setup workstation

> Guide workstation onboarding and profile scaffolding

## Overview

`cloudstic setup workstation` is a guided onboarding flow that gets a new machine backed up quickly. Instead of manually crafting each profile with `cloudstic profile new`, it:

1. Suggests common workstation folders that exist on this machine (Documents, Desktop, Pictures, Videos, Music, developer project folders)
2. Discovers attached portable/external drives (the same logic as [`cloudstic source discover`](/commands/source-discover))
3. Resolves or helps you pick a store to attach the generated profiles to
4. Builds a review-first plan — nothing is written until you confirm it
5. Applies the plan as a single batch write to `profiles.yaml`

<Note>
  Workstation setup is workstation-first: it covers local folders and portable drives. It doesn't set up cloud sources (Google Drive, OneDrive) or SFTP — configure those with `cloudstic profile new` as usual.
</Note>

## Basic Usage

```bash theme={null}
cloudstic setup workstation [options]
```

Interactive by default:

```bash theme={null}
cloudstic setup workstation
```

Preview only, no writes:

```bash theme={null}
cloudstic setup workstation -dry-run
```

## Dry-Run vs. Apply

### Dry-Run

`-dry-run` builds and prints the onboarding plan without any side effects. It does not create the config directory, mutate `profiles.yaml`, initialize a store, or resolve/print secret values. Use it to see what setup would do before committing.

```bash theme={null}
cloudstic setup workstation -dry-run
```

### Interactive Apply (default)

Without `-dry-run`, Cloudstic walks you through:

1. **Store resolution** — if no store exists yet, you're prompted to create one (reusing the same flow as `cloudstic store new`, including encryption setup). If exactly one store is configured, it's used automatically. If multiple stores exist, you're prompted to choose one (or pass `-store-ref`).
2. **Plan review** — for each proposed profile, you confirm creation; if a profile name collides with an existing one, you choose to update the existing profile, create it under a new name, or skip it entirely.
3. **Final confirmation** — a summary table and coverage report are printed, then you confirm the save.

### Non-Interactive Apply

Pass `-yes` to accept all default selections without prompting (requires a store to already exist, or `-store-ref` to be given):

```bash theme={null}
cloudstic setup workstation -yes -store-ref prod-s3
```

If setup can't prompt (no interactive terminal) and `-yes` isn't set, it fails rather than guessing.

## Command Flags

<ParamField path="-dry-run" type="boolean" default="false">
  Preview the generated onboarding plan without writing configuration. Side-effect free: no config directory creation, no store initialization, no secret resolution, no `profiles.yaml` writes.
</ParamField>

<ParamField path="-yes" type="boolean" default="false">
  Accept default plan selections without interactive prompts. Combine with `-store-ref` when more than one store is configured.
</ParamField>

<ParamField path="-json" type="boolean" default="false">
  Write the onboarding plan as JSON instead of human-readable tables. Implies non-interactive plan output (the plan is printed, not applied interactively).
</ParamField>

<ParamField path="-profiles-file" type="string" env="CLOUDSTIC_PROFILES_FILE">
  Path to the profiles YAML file to read and write.
</ParamField>

<ParamField path="-store-ref" type="string">
  Existing store reference to attach to generated profiles. Required (or resolved interactively) when more than one store is configured; falls back to the single existing store automatically when only one exists.
</ParamField>

## What Gets Suggested

### Folders

Cloudstic suggests folders that actually exist on the machine, grouped by category:

* **Core documents** — `~/Documents`
* **Desktop and workspace** — `~/Desktop`
* **Media libraries** — `~/Pictures`, `~/Videos`, `~/Music` (skipped on Windows)
* **Developer projects** — any of `~/Projects`, `~/projects`, `~/code`, `~/src` that exist

`~/Downloads` is detected but intentionally listed under "skipped intentionally" rather than proposed as a profile, since it's typically low-signal/transient data.

### Portable Drives

Any portable/external drive found by the discovery logic (see [`cloudstic source discover`](/commands/source-discover)) is proposed as its own profile, tagged `portable` in addition to `workstation`.

### Generated Profiles

Each selected folder or drive becomes a profile:

* **Name**: derived from the folder/drive name; if that name is already taken, Cloudstic prefixes it with the hostname, then appends a numeric suffix if still colliding
* **Source**: `local:<path>`
* **Store**: the resolved store reference
* **Tags**: `workstation`, plus `portable` for drives

## Example Transcript

```
$ cloudstic setup workstation
Workstation setup plan
Host: loics-macbook
Store: prod-s3 (use-existing)

PROFILE              SOURCE URI              STORE     TAGS                  ACTION
documents             local:/Users/loic/Documents   prod-s3   workstation           create
desktop               local:/Users/loic/Desktop     prod-s3   workstation           create
backup-drive          local:/Volumes/Backup          prod-s3   portable,workstation  create

Protected now:
- Documents (/Users/loic/Documents)
- Desktop (/Users/loic/Desktop)
- Backup Drive (/Volumes/Backup)

Skipped intentionally:
- Downloads (/Users/loic/Downloads)

Create profile "documents" for Documents (/Users/loic/Documents)? [Y/n]: y
Create profile "desktop" for Desktop (/Users/loic/Desktop)? [Y/n]: y
Create profile "backup-drive" for Backup Drive (/Volumes/Backup)? [Y/n]: y

Save workstation setup? [Y/n]: y

Saved 3 profile(s) in ~/.config/cloudstic/profiles.yaml (3 created, 0 updated)
```

### Dry-Run Example

```
$ cloudstic setup workstation -dry-run
Workstation setup plan (dry-run)
Host: loics-macbook
Store: prod-s3 (use-existing)

PROFILE      SOURCE URI                     STORE     TAGS         ACTION
documents    local:/Users/loic/Documents    prod-s3   workstation  create
desktop      local:/Users/loic/Desktop      prod-s3   workstation  create

Protected now:
- Documents (/Users/loic/Documents)
- Desktop (/Users/loic/Desktop)

Skipped intentionally:
- Downloads (/Users/loic/Downloads)
```

No prompts, no writes — the command exits after printing the plan.

## Coverage Review

Every plan (dry-run or applied) reports a coverage summary:

* **Protected now** — folders/drives that will produce (or already have) a profile
* **Skipped intentionally** — suggestions that were deselected, or low-signal paths like Downloads
* **Not available now** — reserved for portable drives seen previously but not currently mounted
* **Warnings** — for example, when a requested `-store-ref` doesn't exist, or when multiple stores are configured and none was specified

## How It Composes

`cloudstic setup workstation` is a thin, review-first layer over existing primitives — it doesn't replace them:

* Uses the same discovery logic as [`cloudstic source discover`](/commands/source-discover) to find portable drives
* Reuses the [`cloudstic store new`](/commands/store-new) flow (including encryption configuration) when no store exists yet
* Writes profiles in the same shape as [`cloudstic profile new`](/commands/profile-new); generated profiles can be edited afterward with `profile new`/`profile show` like any other profile

## See Also

* [cloudstic source discover](/commands/source-discover): The portable-drive discovery step used by this command
* [cloudstic store new](/commands/store-new): Create a store manually
* [cloudstic profile new](/commands/profile-new): Create or edit a single profile manually
* [cloudstic tui](/commands/tui): Interactive dashboard for day-to-day operation after onboarding
* [Sources Overview](/sources/overview): All supported source types