feat: multi-app support, YAML config, Bubble Tea picker, npm/brew distribution

- Multiple X API apps with isolated credentials and tokens
- Interactive default app/user picker (Bubble Tea)
- Single-command defaults: xurl auth default <app> <user>
- Per-request --app override
- YAML .xurl format with auto-migration from legacy JSON
- Credential backfill from env vars into migrated apps
- auth apps add/update/remove/list commands
- auth status shows per-app breakdown
- Homebrew tap via goreleaser
- npm package @xdevplatform/xurl
- Install script no longer requires sudo
- Updated README and SKILL.md

Author: santiagomed

.github/workflows/go.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.20'
+        go-version: '1.24'
 
     - name: Build
       run: go build -v ./...

.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: "1.24"
+
+      - name: Run tests
+        run: go test ./...
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          version: "~> v2"
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.goreleaser.yaml

@@ -50,6 +50,20 @@ changelog:
       - "^docs:"
       - "^test:"
 
+brews:
+  - repository:
+      owner: xdevplatform
+      name: homebrew-tap
+      token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
+    directory: Formula
+    homepage: "https://github.com/xdevplatform/xurl"
+    description: "Auth-enabled curl-like CLI for the X API"
+    license: "MIT"
+    install: |
+      bin.install "xurl"
+    test: |
+      system "#{bin}/xurl", "version"
+
 release:
   footer: >-
 

README.md

@@ -4,15 +4,36 @@ A command-line tool for interacting with the X (formerly Twitter) API, supportin
 
 ## Features
 
+- **Multi-app support** — register multiple X API apps with separate credentials and tokens
 - OAuth 2.0 PKCE flow authentication
 - OAuth 1.0a authentication
-- Multiple OAuth 2.0 account support
-- Persistent token storage
+- Multiple OAuth 2.0 account support per app
+- Default app and default user selection (interactive Bubble Tea picker or single command)
+- Persistent token storage in YAML (`~/.xurl`), auto-migrates from legacy JSON
 - HTTP request customization (headers, methods, body)
+- Per-request app override with `--app`
 
 ## Installation
+
+### Homebrew (macOS / Linux)
+```bash
+brew install xdevplatform/tap/xurl
+```
+
+### npm
+```bash
+npm install -g @xdevplatform/xurl
+```
+
+### Shell script (no sudo required)
+```bash
+curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash
+```
+Installs to `~/.local/bin`. If it's not in your PATH, the script will tell you what to add.
+
+### Go
 ```bash
-curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | sudo bash
+go install github.com/xdevplatform/xurl@latest
 ```
 
 
@@ -22,39 +43,104 @@ curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh |
 
 You must have a developer account and app to use this tool. 
 
-#### App authentication:
+#### Register an app
+
+Register your X API app credentials so they're stored in `~/.xurl` (no env vars needed after this):
+
 ```bash
-xurl auth app --bearer-token BEARER_TOKEN
+xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+```
+
+You can register multiple apps:
+```bash
+xurl auth apps add prod-app --client-id PROD_ID --client-secret PROD_SECRET
+xurl auth apps add dev-app  --client-id DEV_ID  --client-secret DEV_SECRET
 ```
 
+> **Legacy / env-var flow:** You can also set `CLIENT_ID` and `CLIENT_SECRET` as environment variables. They'll be auto-saved into the active app on first use.
+
 #### OAuth 2.0 User-Context
 **Note:** For OAuth 2.0 authentication, you must specify the redirect URI in the [X API developer portal](https://developer.x.com/en/portal/dashboard).
 
 1. Create an app at the [X API developer portal](https://developer.x.com/en/portal/dashboard).
 2. Go to authentication settings and set the redirect URI to `http://localhost:8080/callback`.
 ![Setup](./assets/setup.png)
 ![Redirect URI](./assets/callback.png)
-3. Set the client ID and secret in your environment variables.
-```env
-export CLIENT_ID=your_client_id
-export CLIENT_SECRET=your_client_secret
+3. Register the app (if you haven't already):
+```bash
+xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
 ```
 4. Get your access keys:
 ```bash
 xurl auth oauth2
 ```
+
+#### App authentication (bearer token):
+```bash
+xurl auth app --bearer-token BEARER_TOKEN
+```
+
 #### OAuth 1.0a authentication:
 ```bash
 xurl auth oauth1 --consumer-key KEY --consumer-secret SECRET --access-token TOKEN --token-secret SECRET
 ```
 
-### Authentication Management
-View authentication status:
+### Multi-App Management
+
+List registered apps:
+```bash
+xurl auth apps list
+```
+
+Update credentials on an existing app:
+```bash
+xurl auth apps update my-app --client-id NEW_ID --client-secret NEW_SECRET
+```
+
+Remove an app:
+```bash
+xurl auth apps remove old-app
+```
+
+Set the default app and user — **interactive picker** (uses Bubble Tea):
+```bash
+xurl auth default
+```
+
+Set the default app and user — **single command**:
+```bash
+xurl auth default my-app              # set default app
+xurl auth default my-app alice        # set default app + default user
+```
+
+Use a specific app for a single request:
+```bash
+xurl --app dev-app /2/users/me
+```
+
+### Authentication Status
+View authentication status across all apps:
 ```bash
 xurl auth status
 ```
 
-Clear authentication:
+Example output:
+```
+▸ my-app  [client_id: VUttdG9P…]
+    ▸ oauth2: alice
+      oauth2: bob
+      oauth1: ✓
+      bearer: ✓
+
+  dev-app  [client_id: OTHER789…]
+      oauth2: (none)
+      oauth1: –
+      bearer: –
+```
+
+`▸` on the left = default app. `▸` next to a user = default user.
+
+### Clear Authentication
 ```bash
 xurl auth clear --all                       # Clear all tokens
 xurl auth clear --oauth1                    # Clear OAuth 1.0a tokens
@@ -190,7 +276,28 @@ xurl '/2/media/upload?command=STATUS&media_id=MEDIA_ID'
 
 ## Token Storage
 
-Tokens are stored securely in `~/.xurl` in your home directory.
+Tokens and app credentials are stored in `~/.xurl` in YAML format. Each registered app has its own isolated set of tokens. Example:
+
+```yaml
+apps:
+  my-app:
+    client_id: abc123
+    client_secret: secret456
+    default_user: alice
+    oauth2_tokens:
+      alice:
+        type: oauth2
+        oauth2:
+          access_token: "..."
+          refresh_token: "..."
+          expiration_time: 1234567890
+    bearer_token:
+      type: bearer
+      bearer: "AAAA..."
+default_app: my-app
+```
+
+> **Migration:** If you have an existing JSON-format `~/.xurl` file from a previous version, it will be automatically migrated to the new YAML multi-app format on first use. Your tokens are preserved in a `default` app.
 
 ## Contributing
 Contributions are welcome!

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xurl
-description: A curl-like CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint. Supports OAuth 2.0, OAuth 1.0a, and app-only auth.
+description: A curl-like CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint. Supports multiple apps, OAuth 2.0, OAuth 1.0a, and app-only auth.
 ---
 
 # xurl — Agent Skill Reference
@@ -11,24 +11,40 @@ description: A curl-like CLI tool for making authenticated requests to the X (Tw
 
 ## Prerequisites
 
-Before using any command you must be authenticated. Run `xurl auth status` to check. If not authenticated, set up one of:
+Before using any command you must be authenticated. Run `xurl auth status` to check.
+
+### Register an app (recommended)
 
 ```bash
-# Option 1 — OAuth 2.0 (user‑context, most common)
-export CLIENT_ID=your_client_id
-export CLIENT_SECRET=your_client_secret
+# Register your X API app credentials (stored in ~/.xurl)
+xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+
+# Then authenticate
 xurl auth oauth2
+```
+
+You can register multiple apps and switch between them:
+```bash
+xurl auth apps add prod-app --client-id PROD_ID --client-secret PROD_SECRET
+xurl auth apps add dev-app  --client-id DEV_ID  --client-secret DEV_SECRET
+xurl auth default prod-app          # set default app
+xurl auth default prod-app alice    # set default app + user
+xurl --app dev-app /2/users/me      # one-off override
+```
+
+### Other auth methods
 
-# Option 2 — OAuth 1.0a
+```bash
+# OAuth 1.0a
 xurl auth oauth1 \
   --consumer-key KEY --consumer-secret SECRET \
   --access-token TOKEN --token-secret SECRET
 
-# Option 3 — App‑only bearer token
+# App‑only bearer token
 xurl auth app --bearer-token TOKEN
 ```
 
-Tokens are persisted to `~/.xurl`. Once authenticated, every command below will auto‑attach the right `Authorization` header.
+Tokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. Once authenticated, every command below will auto‑attach the right `Authorization` header.
 
 ---
 
@@ -66,6 +82,15 @@ Tokens are persisted to `~/.xurl`. Once authenticated, every command below will
 | List DMs | `xurl dms -n 10` |
 | Upload media | `xurl media upload path/to/file.mp4` |
 | Media status | `xurl media status MEDIA_ID` |
+| **App Management** | |
+| Register app | `xurl auth apps add NAME --client-id ID --client-secret SEC` |
+| List apps | `xurl auth apps list` |
+| Update app creds | `xurl auth apps update NAME --client-id ID` |
+| Remove app | `xurl auth apps remove NAME` |
+| Set default (interactive) | `xurl auth default` |
+| Set default (command) | `xurl auth default APP_NAME [USERNAME]` |
+| Use app per-request | `xurl --app NAME /2/users/me` |
+| Auth status | `xurl auth status` |
 
 > **Post IDs vs URLs:** Anywhere `POST_ID` appears above you can also paste a full post URL (e.g. `https://x.com/user/status/1234567890`) — xurl extracts the ID automatically.
 
@@ -216,10 +241,11 @@ xurl post "lol" --media-id MEDIA_ID
 
 ## Global Flags
 
-These flags work on every shortcut command:
+These flags work on every command:
 
 | Flag | Short | Description |
 |---|---|---|
+| `--app` | | Use a specific registered app for this request (overrides default) |
 | `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` |
 | `--username` | `-u` | Which OAuth2 account to use (if you have multiple) |
 | `--verbose` | `-v` | Print full request/response headers |
@@ -332,6 +358,24 @@ xurl mentions -n 20
 xurl timeline -n 20
 ```
 
+### Set up multiple apps
+```bash
+# Register two apps
+xurl auth apps add prod --client-id PROD_ID --client-secret PROD_SECRET
+xurl auth apps add staging --client-id STG_ID --client-secret STG_SECRET
+
+# Authenticate users on each
+xurl auth default prod
+xurl auth oauth2                       # authenticates on prod app
+
+xurl auth default staging
+xurl auth oauth2                       # authenticates on staging app
+
+# Switch between them
+xurl auth default prod alice           # prod app, alice user
+xurl --app staging /2/users/me         # one-off request against staging
+```
+
 ---
 
 ## Error Handling
@@ -348,4 +392,7 @@ xurl timeline -n 20
 - **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
 - **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token.
 - **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
-- **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts and switch between them with `--username` / `-u`.
+- **Multiple apps:** Register multiple apps with `xurl auth apps add`. Each app has its own isolated credentials and tokens. Switch with `xurl auth default` or `--app`.
+- **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `--username` / `-u` or set a default with `xurl auth default APP USER`.
+- **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token.
+- **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens.

api/client_test.go

@@ -25,10 +25,14 @@ func createTempTokenStore(t *testing.T) (*store.TokenStore, string) {
 		t.Fatalf("Failed to create temp directory: %v", err)
 	}
 
-	tempFile := filepath.Join(tempDir, "tokens.json")
+	tempFile := filepath.Join(tempDir, ".xurl")
 	tokenStore := &store.TokenStore{
+		Apps:       make(map[string]*store.App),
+		DefaultApp: "default",
+		FilePath:   tempFile,
+	}
+	tokenStore.Apps["default"] = &store.App{
 		OAuth2Tokens: make(map[string]store.Token),
-		FilePath:     tempFile,
 	}
 
 	return tokenStore, tempDir