subgraph.site

docs · users

Getting started

In under a minute: install the CLI, sign in with your handle, and upload your first item.

1. Install Bun

The @subgraph/cli is Bun-native. On macOS or Linux: 

curl -fsSL https://bun.sh/install | bash

On Windows, use the PowerShell installer from bun.sh. Minimum: Bun 1.3.

2. Clone and install

The CLI isn't on npm yet. From source: 

git clone <repo>/subgraph-site
cd subgraph-site
bun install

3. Sign in

From the repo root: 

cd packages/cli
bun run src/index.ts login me.bsky.social

Your browser will open to your PDS's OAuth flow. Authenticate. You'll see a "Signed in. Close this tab." page; the CLI will show logged in as did:plc:…. Session tokens (DPoP-bound, refreshable) are stored at ~/.config/subgraph/session.json.

The sign-in flow uses an atproto OAuth 2.0 loopback redirect on 127.0.0.1:21849. If that port is in use, kill the other process and try again — this is a known limitation we'll fix with an ephemeral port.

4. Upload

Photos, video, audio, recipes, files — the CLI auto-detects the kind:

bun run src/index.ts upload ~/Photos/*.jpg --series "Joshua Tree, Spring 2026"
bun run src/index.ts upload ~/Videos/demo.mp4 --title "Demo"
bun run src/index.ts upload ~/audio/episode-001.mp3 --title "Episode 1"
bun run src/index.ts recipe publish ./tacos.md

5. Long-form articles

Articles write to site.standard.document — they need a publication (site container) first. You can run multiple publications if you want separate "sites" (blog, recipes, photos, etc). 

subgraph pub create --name "My Blog" --url "https://example.com"
subgraph pub list
subgraph doc publish ./post.md --publication at://did:plc:.../site.standard.publication/<rkey>

6. Other commands

subgraph whoami                              # show current identity
subgraph list                                # list your items
subgraph list series                         # list your series
subgraph pub list                            # list publications
subgraph series create "My trip" --publication at://...
subgraph delete at://did:plc:.../site.subgraph.item/<rkey>
subgraph logout                              # clear the session

--publication is optional on every subgraph publish. Use it to claim a canonical web home for the thing you're publishing. Omit it for raw PDS-level content that isn't attached to any website.

Troubleshooting

  • Port 21849 in use — something (often a previous run) holds the loopback port. Find and kill: lsof -i :21849 then kill <pid>.
  • Sign-in timed out — the browser closed or the user cancelled before completing auth. Run subgraph login again.
  • "state mismatch on OAuth callback" — the callback URL carries a state value that doesn't match what we sent. This is CSRF protection working as intended; a stale browser tab or a concurrent sign-in attempt is the usual cause. Close any open OAuth tabs, retry.