# DeskPilot (CLI prototype)

DeskPilot is a named workspace launcher: define a "workspace" as a list of
URLs, commands/programs, and files or folders, save it once, and then
launch the whole set with a single command. This is a genuinely working
prototype -- it saves real JSON workspace files and, on `open`, actually
opens URLs/paths with your OS's default handler and spawns commands as
real detached processes. Window positioning, per-monitor layout profiles,
and taskbar customization from the full DeskPilot product concept require
native Win32 (Windows), AppKit (macOS), or X11 (Linux) window-management
APIs that a portable, dependency-free Go CLI cannot reach -- those remain
roadmap items. See ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o deskpilot .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o deskpilot.exe .
    GOOS=darwin  GOARCH=arm64 go build -o deskpilot .

## Usage

DeskPilot stores workspace definitions as small JSON files in a workspace
directory (default: ~/.deskpilot, override anywhere with --dir).

    deskpilot save <name> --add TYPE=TARGET [--add TYPE=TARGET ...] [--dir <workspace-dir>]
    deskpilot list [--dir <workspace-dir>]
    deskpilot open <name> [--dir <workspace-dir>] [--dry-run]
    deskpilot remove <name> [--dir <workspace-dir>] [--apply]
    deskpilot help

### save

Builds a workspace from one or more repeatable --add TYPE=TARGET flags
and writes it to <workspace-dir>/<name>.json (the directory is created if
missing). Prints a confirmation with the saved path and item count.

    deskpilot save work \
      --add url=https://mail.example.com \
      --add "command=code /home/user/project" \
      --add path=/home/user/Documents

For --add command=..., the value is split on whitespace into a program
plus arguments (a simple strings.Fields split) -- quoting an argument
that itself contains spaces is not supported in this prototype.

### list

Lists every saved workspace (*.json) in the workspace directory, showing
each workspace's name and item count.

    deskpilot list

### open

Loads <workspace-dir>/<name>.json and processes each item in order:

  - url items are opened with the OS default handler.
  - path items (files or folders) are opened with the OS default handler,
    same mechanism as url.
  - command items are launched via os/exec and NOT waited on -- DeskPilot
    starts them and immediately returns, since these are meant to be
    apps that stay open, not one-shot scripts.

This launches real processes and opens real URLs/files. Pass --dry-run to
preview what each item would do without launching anything:

    deskpilot open work --dry-run
    deskpilot open work

Per-item failures (for example a missing default-handler binary such as
xdg-open on a minimal Linux install) are reported individually and do NOT
abort the rest of the workspace. A final summary line reports how many
items launched successfully and how many failed.

### remove

Deletes a saved workspace file. Without --apply this is a dry run that
only confirms the file exists and would be removed; pass --apply to
actually delete it.

    deskpilot remove work
    deskpilot remove work --apply

## Workspace file format

Each workspace is one JSON file, e.g. ~/.deskpilot/work.json:

    {
      "name": "work",
      "items": [
        { "type": "url", "target": "https://mail.example.com" },
        { "type": "command", "target": "code", "args": ["/home/user/project"] },
        { "type": "path", "target": "/home/user/Documents" }
      ]
    }

Item types:

  - "url"     -- target is a URL, opened with the OS default handler.
  - "command" -- target is a program name/path, args is its argument
                 list; run via os/exec, launched detached (not waited on).
  - "path"    -- target is a file or folder path, opened with the OS
                 default handler (same mechanism as "url").

The opener mechanism is platform-specific and implemented via
runtime.GOOS, with no external dependencies:

  - windows: cmd /C start "" <target>
  - darwin:  open <target>
  - other:   xdg-open <target>

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds --
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.