macOS CLI: shuttle git · shuttle drive · shuttle chrome · shuttle notion.

Install Python and git with Homebrew:

brew install python@3.12 git

Optional: gh (GitHub CLI) for cursor-skills workflows — not required by shuttle-cli itself.

Shuttle reads config/config.yaml in the clone, or ~/.config/shuttle-cli/ after install. Override the directory with SHUTTLE_CONFIG_DIR.

Copy the bundled config/ tree and edit paths for your machine before daily use:

Example config.yaml:

backup:
  tags_dir: ~/Library/Mobile Documents/com~apple~CloudDocs/git-tags
  repositories:
    - path: ~/git-local/shuttle-cli
    - path: ~/git-local/my-other-repo

notion:
  database_id: your-notion-database-id
  task_directory: data/tasks

chrome:
  profile: Default
  bookmarks_file: ~/git-local/shuttle-cli/data/bookmarks/bookmarks.html
  downloads_dir: ~/Downloads

Cloud providers: config/drives.yaml. Notion token: export NOTION_TOKEN=... (never commit).

Environment overrides (optional): SHUTTLE_BOOKMARKS_FILE, SHUTTLE_DOWNLOADS_DIR, SHUTTLE_CONFIG_DIR, NOTION_TOKEN.

Local setup is for using shuttle only (runtime deps). Verification always runs in Docker — same image locally and in CI.

./scripts/bootstrap.sh          # venv + runtime install
source .venv/bin/activate
python -m shuttle --help

Optional install to ~/.local/bin:

./scripts/install.sh
shuttle git --help
shuttle drive --help

Do not run pytest on the host; use ./scripts/test-unit.sh and ./scripts/test-integration.sh instead.

Run from inside a repository (cd into the repo first).

Short alias: shuttle g push --yes == shuttle git push --yes.

Shell wrappers: scripts/git/ (e.g. ./scripts/git/review.sh). See docs/git.md.

Safety: destructive actions (reset, clean, delete, push) require --yes or an interactive confirmation. Default shuttle git start aligns main then branches; pass --no-prep to branch from the current state.

Local hub: iCloud git-tags/{repo}/{tag}.zip (via backup.tags_dir). Cloud: append-only upload to Google Drive, OneDrive, Proton.

Typical end-of-day:

shuttle git tag --yes && shuttle git zip    # single repo (cwd)
shuttle drive upload                        # push missing zips to cloud

Multi-repo:

shuttle drive sync                          # ingest all repos + upload all clouds
# or step by step:
shuttle drive ingest
shuttle drive status
shuttle drive upload

git zip is the quick path for the current repo; drive ingest iterates configured repositories (or one PATH). See docs/drive.md · issue #4.

Shell wrappers: scripts/drive/ (status.sh, ingest.sh, upload.sh, sync.sh).

Browser integrations; bookmarks is the first subcommand. Path: chrome.bookmarks_file in config.

shuttle chrome bookmarks ingest   # Chrome → local HTML file
shuttle chrome bookmarks deploy   # local file → Chrome

Shell wrappers: ./scripts/chrome/ingest.sh · ./scripts/chrome/deploy.sh (deprecated: import.sh / export.sh).

See docs/bookmarks.md · epic #24 (shell scripts: #1).

Local tasks: notion.task_directory (data/tasks/). Auth: NOTION_TOKEN + notion.database_id.

See docs/notion.md · epic #2 · children #20–#23.

Local Docker monitor and cleanup (requires docker on PATH; no container start):

Shell wrappers live in scripts/docker/ (e.g. ./scripts/docker/reset.sh --yes).

Destructive commands use the write gate; pass --yes in scripts.

Requires Docker Desktop on macOS (or Docker Engine on Linux). The shuttle-cli:dev Linux image is the only supported test environment:

./scripts/docker/build-image.sh   # build once (or auto-build on first test run)
./scripts/test-unit.sh            # unit tests (≥80% coverage)
./scripts/test-integration.sh     # full pytest + smoke + live docker
./scripts/docker/shell.sh         # onboard: interactive shell in container

See docs/docker.md.

• Setup
• Git commands
• Drive (local + cloud)
• Chrome · Notion
• Docker integration
• Configuration
• Architecture

• cursor-skills — @gh-* AI workflows for issues/PRs
• Cloud drive epic: shuttle-cli #4
• Bootstrap spec: shuttle-cli #3
• Chrome: shuttle-cli #24 · bookmarks scripts #1
• Docker integration: shuttle-cli #9