# Poly

> Poly is a cross-platform CLI package manager: one command (`poly install <name>`) that
> routes to pip, npm, Homebrew, cargo, go install, or its own checksum-verified binary
> "tap" downloads, whichever actually has the package, on macOS, Linux, and Windows.
> Poly works alongside pip/npm/brew rather than replacing them — it unifies them behind
> a single interface, keeps one local record (`~/.poly/manifest.json`) of what got
> installed through which, and can write that state to a committable `poly.json` so a
> second machine can reproduce it with a single `poly install`.

Poly is free and open source. A one-time €0.99 "Pro" unlock adds concurrent multi-package
installs and automatic background package upgrades — it does not gate any package or
formula; the entire built-in tap catalog is free.

## Install

- macOS installer (.pkg, universal Intel+Apple Silicon): https://github.com/opencorp2030-ctrl/poly/releases/latest/download/poly-macos.pkg
- Windows installer (.exe, installs to %LOCALAPPDATA%\Poly, no admin needed): https://github.com/opencorp2030-ctrl/poly/releases/latest/download/poly-setup.exe
- All prebuilt binaries and release notes: https://github.com/opencorp2030-ctrl/poly/releases/latest
- Build from source (any OS, Go 1.21+): `git clone https://github.com/opencorp2030-ctrl/poly.git && cd poly && go build -o poly .`

## Commands

- `poly install [[adapter:]name[@version] ...]` — install packages, auto-routed or forced with a prefix like `pip:requests`. Multiple names install sequentially (free) or concurrently (Pro). No arguments reads `./poly.json` and installs everything listed there.
- `poly remove name` — uninstall via whichever adapter installed it.
- `poly list` — show everything poly has installed, and through which adapter.
- `poly search [adapter:]name` — exact-name existence + latest-version check, across every adapter or one forced.
- `poly info [adapter:]name` — like search, plus summary, homepage, and local install status.
- `poly init [--force]` — write `poly.json` from currently poly-installed packages, version-pinned, for reproducible environments.
- `poly upgrade` — check every installed package against its adapter's latest version and reinstall what's outdated.
- `poly self-update` — check GitHub releases, download, SHA-256-verify, and atomically replace the running poly binary.
- `poly login` / `poly logout` / `poly account` — Supabase-backed account: sign in, sign out, print your email/username/bio/plan.
- `poly send name version path` — publish a file or directory to the community registry under your signed-in account. Installable by anyone via `poly install community:name` (never auto-detected, to prevent name-squatting on real packages).
- `poly version` — print the build version and, if signed in, your account/plan.
- `poly doctor` — check for common setup problems: missing toolchains, an unwritable `~/.poly`, `~/.poly/bin` missing from `PATH`, GitHub reachability.

## Adapters (in auto-detect order)

1. `tap` — direct binary download from a pinned URL in an embedded/local YAML formula, SHA-256 verified, extracted into `~/.poly/bin`. No runtime needed.
2. `brew` — shells to `brew install`/`brew upgrade`. Search hits the public formulae.brew.sh API.
3. `pip` — shells to `pip3 install --upgrade` (or `==version` pinned). Search hits the PyPI JSON API.
4. `npm` — shells to `npm install -g name@latest` (or `@version`). Search hits the npm registry API.
5. `cargo` — shells to `cargo install --force`. Search hits the crates.io API.
6. `go` — shells to `go install <module>@version`; takes a full module import path, not a short name (e.g. `golang.org/x/tools/cmd/goimports`), so it's realistically only used via an explicit `go:` prefix.

`community` is a 7th adapter (user-published packages, via `poly send`) that is deliberately excluded from auto-detect order — only reachable via an explicit `community:` prefix, so a published name can never silently shadow a real pip/npm/crates.io package.

## MCP server (for AI assistants)

Poly runs a remote MCP server (Streamable HTTP transport, plus OAuth 2.1 + Dynamic Client
Registration for clients like Claude.ai/ChatGPT that only support OAuth for remote
connectors) at `https://iuymslcbbrbahxbfuzrr.supabase.co/functions/v1/mcp`, hosted as a
Supabase Edge Function, so an AI assistant can act as a signed-in Poly user without ever
handling that user's email/password. Auth is a personal access token generated on
account (shown once, revocable any time) -- either sent directly as `Authorization:
Bearer <token>`, or pasted into the OAuth connect page during the "Add custom connector"
flow (the resulting OAuth access_token IS that same personal access token). Tools
exposed: `whoami`, `search_packages`/`search_dependencies` (community registry vs.
pip+npm+crates.io+Homebrew+tap+community all at once), `get_package`, `list_own_packages`,
`publish_package` (base64-encoded file in the tool call args — same first-come-first-served
ownership rules and SHA-256 verification as `poly send`; an assistant can never mark a
package "official"; the tool description explicitly warns against building an HTML/web
app -- published packages are CLI scripts/binaries, not web pages; an optional `category:
"integration"` argument lists the package on poly.candygate.eu/integrations), `search_members`,
`get_profile`, `update_profile`, `update_avatar`, `delete_package`, `get_stats`
(`update_profile`/`update_avatar`/`delete_package` act only on the token's own account/
packages; `delete_package` removes both the DB entry and the stored file and cannot be
undone). Apps store tools: `search_apps`, `get_app`, `list_own_apps`, `publish_app`
(the web-app/desktop-app/mobile-app counterpart to `publish_package` -- category, content
rating, platforms, base64 icon/screenshots, pricing (free or paid via Stripe Checkout),
ads/IAP/permission disclosures, and a release in one call; publishing a name the token's
account already owns updates that app in place and leaves omitted optional fields
unchanged; a release needs `download_url` or a base64 `file_base64` capped at 20MB),
`delete_app`. Also exposed: social (`follow_user`, `unfollow_user`, `list_followers`,
`list_following`, `get_follow_status`, `send_friend_request`, `accept_friend_request`,
`decline_friend_request`, `remove_friend`, `list_friend_requests`, `list_friends`),
notifications (`list_notifications`, `mark_notification_read`,
`mark_all_notifications_read`, `delete_notification`, `get_notification_prefs`,
`update_notification_prefs`), profile extras (`update_bio_rich` — up to 3500 chars, light
HTML formatting; `update_bio_photo` — base64 image into one of 2 photo slots; `set_dev_mode`;
`check_banned`), and admin/staff-only tools mirroring the hidden admin page
(`admin_ban_user`, `admin_unban_user`, `admin_block_package`, `admin_unblock_package`,
`admin_search_users`, `admin_search_packages`, `admin_send_notification`,
`admin_list_banned_users`, `admin_list_blocked_packages` — authorization is enforced
server-side per-token; staff can only broadcast notifications to everyone, only the admin
account can target specific usernames or ban/block anything). Deliberately NOT exposed via
MCP: creating, listing, or revoking personal access tokens, and badges (admin-SQL-only,
no bypass) -- an assistant can use the access it's given but never grant or manage its own.
Full setup instructions, including the Claude Desktop/Code config JSON:
https://poly.candygate.eu/docs#mcp

poly.candygate.eu/integrations lets a signed-in user describe an integration in plain
language (e.g. "an Alexa skill that reads out my package's weekly downloads"); the page
saves the request and opens Claude.ai with a ready-made prompt (also shown as copyable text
for Claude Code/Desktop/any other MCP client) instructing the assistant to search the
registry, build a CLI package, and publish it via `publish_package` with `category:
"integration"` -- no separate AI infrastructure on Poly's side, it just hands your own
already-connected assistant a well-formed task.

## Key files and formats

- `poly.json` (project-local, written by `poly init`): `{"packages": ["tap:ripgrep@15.1.0", "npm:eslint@9.2.0"]}`. `poly install` with no arguments reads this.
- Tap formula YAML (`~/.poly/taps/<name>.yaml` or embedded in the binary): fields `name`, `description`, `homepage`, `version`, `binary`, `tier` (`free` or `pro`), and `artifacts` keyed by `<GOOS>_<GOARCH>` each with `url` and `sha256`.
- `~/.poly/manifest.json` — local record of installed packages.
- `~/.poly/credentials.json` (mode 0600) — signed-in session.
- `~/.poly/auto-update.log` — output of the background self-update / auto-upgrade checks.

## Site

- Homepage: https://poly.candygate.eu/
- Full docs: https://poly.candygate.eu/docs
- Account (sign up / manage plan): https://poly.candygate.eu/account
- Community directory + live download/member stats: https://poly.candygate.eu/community
- Apps store: browse free/paid apps published by the community, rate and review them: https://poly.candygate.eu/apps
- Public app detail pages: https://poly.candygate.eu/app?slug=<app-slug>
- Publish an app (Play Console-style listing form: icon, screenshots, category, content rating, pricing, data safety, release): https://poly.candygate.eu/publish-app
- Integrations: describe one in plain language, your connected AI assistant builds and publishes it: https://poly.candygate.eu/integrations
- Cross-ecosystem dependency search (pip/npm/crates.io/Homebrew/community, live): https://poly.candygate.eu/dependencies
- Public user profiles: https://poly.candygate.eu/profile?u=<username>
- Public package detail pages: https://poly.candygate.eu/package?name=<package>
- Changelog: https://poly.candygate.eu/changelog
- Roadmap: https://poly.candygate.eu/roadmap
- System status: https://poly.candygate.eu/status
- Poly vs. Homebrew/npm/cargo/uv/Scoop: https://poly.candygate.eu/compare
- Leaderboard (top publishers, most-followed members): https://poly.candygate.eu/leaderboard
- Badge glossary: https://poly.candygate.eu/badges
- Contact: https://poly.candygate.eu/contact
- Press/brand kit: https://poly.candygate.eu/press
- Site directory (every page not in the main nav): https://poly.candygate.eu/search
- Source code, issues: https://github.com/opencorp2030-ctrl/poly