Orbit keeps documents, source code, and local project material in the places where they belong:

 iCloud project                 optional wrapper              canonical Git repo
 notes, assets, exports   ←→    local control plane    ←→    canonical source

The wrapper is optional. Orbit creates local links between these surfaces; it does not move or copy source code into the iCloud project.

With Homebrew:

brew install SuuSoJeat/tap/orbit

Without Homebrew:

curl -fsSL https://github.com/SuuSoJeat/orbit/releases/latest/download/orbit-install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The portable installer uses ~/.local. The repository and its releases must be public for this command to work for everyone; until then, it is available to repository collaborators only.

Create an iCloud project:

orbit new "Acme Product" --category companies

Add a local wrapper during creation:

orbit new "Acme Product" \
  --category companies \
  --with-wrapper

For a company/client project, Orbit can guide you through numbered pickers. The same flow can be scripted:

orbit new "Example Project Platform" \
  --company "Example Company" \
  --client "Example Client" \
  --with-wrapper

Configure consumer-specific locations before using category-based creation:

orbit config init
orbit config check

With no configuration file, Orbit uses these defaults:

~/Repositories
~/Library/Mobile Documents/com~apple~CloudDocs/Workspace/Companies
~/Library/Mobile Documents/com~apple~CloudDocs/Workspace/Ventures

The configuration is stored at ~/.config/orbit/config, or at the path specified by ORBIT_CONFIG or the global --config PATH option. It is consumer-specific and should not be committed. Use orbit config show to inspect the resolved paths. To add an explicit namespace below the iCloud Drive root, use orbit config init --icloud-profile NAME.

Attach an existing canonical repository:

orbit attach \
  "$HOME/Repositories/acme-product-orbit" \
  "$HOME/Repositories/Acme/product"

Attach multiple repositories to the same wrapper:

orbit attach \
  "$HOME/Repositories/Acme/product" \
  "$HOME/Repositories/Acme/product-docs"

Repository names default to the folder name. Override one explicitly when needed:

orbit attach --name docs "$HOME/Repositories/Acme/product-docs"

Orbit records attachments as named sections and creates one symlink per repository below local/repo/.

Check the boundaries and see the configured destinations:

orbit doctor "$HOME/Repositories/acme-product-orbit"
orbit open "$HOME/Repositories/acme-product-orbit" --dry-run

From inside a wrapper, Orbit discovers its path automatically:

cd "$HOME/Repositories/acme-product-orbit"
orbit doctor
orbit open --dry-run
orbit attach "$HOME/Repositories/Acme/product"

orbit new [PROJECT_NAME] [--category companies|ventures]
            [--company NAME] [--client NAME|--no-client]
            [--icloud-root PATH] [--with-wrapper] [--wrapper-root PATH]

Use --category ventures for a project directly under the ventures iCloud root. Company projects can use --company NAME and --client NAME, or --no-client for a company-level project. Omit NAME or the company/client values to use the interactive pickers.

--wrapper-root PATH also enables the local wrapper and lets you choose its location. Otherwise, Orbit uses the configured wrapper_root, which defaults to repository_root:

~/Repositories/<project-slug>-orbit

--icloud-root PATH creates a one-off project and bypasses the category roots in the consumer configuration.

• Keep notes, references, assets, exports, and other sync-worthy documents in the iCloud project.
• Keep the canonical Git repository outside iCloud, normally under the configured repository_root.
• Keep secrets, credentials, .git directories, dependencies, and build output out of the iCloud project.
• Use orbit doctor before relying on a wrapper or attached repository.

orbit undo records creations under ~/.local/state/orbit/creations/ and only removes paths recorded for the creation you select.

Development, testing, CI, release, packaging, and wrapper-template guidance lives in CONTRIBUTING.md.