xurl CLI: Installation, OAuth Setup, and First API Calls

Why xurl exists for X API command-line work

xurl reduces the repeated setup behind direct X API requests. It is aimed at developers who already have an X developer account and application but need a compact interface for authentication, account selection, and endpoint calls. The central idea is familiar from `curl`: invoke an X API path from a terminal rather than assembling every request through application code.

The project goes beyond a bare HTTP wrapper by preserving app-specific client credentials, OAuth tokens, redirect URIs, default users, and default apps. That makes it useful for work involving separate development and production applications, several OAuth 2.0 users, or a mixture of OAuth 1.0a, OAuth 2.0, and app-only credentials. A per-request `--app` option can also avoid changing the selected default.

The scope is narrower than a general API development framework. xurl does not present itself as a code generator, endpoint wrapper library, response model, or mocking service. Its job is terminal interaction with the X API, including an `xurl chat` command built around the official `chat-xdk` encryption library. This makes it a practical companion for API inspection, scripting, and authenticated manual operations.

How xurl resolves credentials and API requests

Applications are registered in `~/.xurl/auth.yml`. Each named app can contain a client ID, client secret, and redirect URI, while OAuth tokens are stored in the same persistent authentication layout. The README also states that xurl migrates automatically from its legacy single-file layout. That is an operational migration users do not have to script themselves.

For OAuth 2.0, redirect URI resolution has a defined order: the `REDIRECT_URI` environment variable takes precedence, followed by the app's stored `redirect_uri`, and finally the built-in `http://localhost:8080/callback`. When the effective URI uses `localhost`, xurl listens on both `127.0.0.1` and `::1`. This accommodates browser loopback behavior, but it also means the developer portal and local tool must agree on the registered URI.

Request customization remains close to the `curl` model. xurl supports headers, methods, and request bodies, while authentication can be selected at request time. For example, app-only credentials are named for the authentication mode rather than the bearer scheme because OAuth 2.0 user tokens are also sent as `Authorization: Bearer`. This distinction matters when reading output or composing commands.

Installing xurl and completing an OAuth 2.0 first login

For npm users, install the globally available package, then confirm that the `xurl` command is available through your shell path:

npm install -g @xdevplatform/xurl

macOS users can use the documented Homebrew cask instead:

brew install --cask xdevplatform/tap/xurl

Go installations require the repository's declared Go 1.24.2 toolchain because `go.mod` declares `go 1.24.2`. Install the latest module version with:

go install github.com/xdevplatform/xurl@latest

Before OAuth, create an app in the X API developer portal and register its credentials. Replace the placeholder values only with credentials issued for that app:

xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Start the browser-based user authorization flow for the named application:

xurl auth oauth2 --app my-app

The redirect URI configured in the developer portal must match xurl's effective value. If no override is set, that value is `http://localhost:8080/callback`. After authorization, `xurl auth status` reports authentication status across registered apps and shows each effective redirect URI.

Remote-host login and the first /2/users/me request

The normal OAuth 2.0 flow waits for a browser callback on `localhost`. The README identifies this as unsuitable for a remote server because its callback is not reachable from that machine. On such hosts, use the documented headless mode:

xurl auth oauth2 --app my-app --headless

xurl prints an authorization URL. Open it on a device with a browser, approve access, and paste either the resulting redirect URL or its `code` value back into the prompt. The page failing to load is expected in this mode because the authorization code is in the URL. No local callback listener is needed.

After a token is stored, a direct account check can be made with the same endpoint shown in the per-request app example:

xurl --app dev-app /2/users/me

That command demonstrates the request model: place `--app` before the API path and xurl uses that app for this invocation without changing the default. If `/2/users/me` does not reliably return a username, the README documents explicit-handle authentication:

xurl auth oauth2 --app my-app YOUR_USERNAME

This preserves the association between the OAuth 2.0 token and the expected username.

OAuth 1.0a, app-only credentials, and multi-app selection

OAuth 1.0a requests four values from an existing X application. Register those values as follows:

xurl auth oauth1 --consumer-key KEY --consumer-secret SECRET --access-token TOKEN --token-secret SECRET

For app-only access, the portal's Bearer Token can be supplied as an argument:

xurl auth app-only BEARER_TOKEN

The README also provides a stdin route that keeps the token out of shell history:

cat token.txt | xurl auth app-only -

Multiple named applications can coexist. List them through `xurl auth apps list`, update a stored credential or redirect URI with `xurl auth apps update`, or remove an obsolete entry with `xurl auth apps remove old-app`. The latter is a local credential-management operation; it does not remove the corresponding application from the X developer portal.

Interactive selection is available through `xurl auth default`, which uses a Bubble Tea picker. Scripted environments can instead set the app and optional user directly:

xurl auth default my-app alice

This split is practical, although automation that cannot present an interactive terminal should use the non-interactive form or an explicit `--app` override.

X developer enrollment and failure modes in xurl

A successful OAuth exchange does not guarantee that every X API request will succeed. The README specifically calls out `client-forbidden` and `client-not-enrolled` responses from X even when authentication and tokens are otherwise valid. It directs users to `Apps`, then `Manage apps`, open the application, use `Move to package`, choose `Pay-per-use`, and move it to the `Production` environment.

This failure belongs to app configuration at X rather than a missing command-line credential. Engineers should distinguish it from callback failure. The callback URI must match the developer portal, and a headless login is necessary when `localhost` on the execution host cannot receive the browser redirect.

Remote access also requires careful interpretation of the headless output. The authorization page may fail after approval, but that does not necessarily mean approval failed because the code remains available in the redirect URL. Conversely, retaining a token does not resolve enrollment or package problems on the X side.

The README excerpt does not document token revocation, credential migration rollback, or a recovery procedure if `~/.xurl/auth.yml` is damaged. It does document automatic migration from the legacy layout, but users who depend on xurl should inspect those files before removing backups or changing authentication modes.

xurl compared with curl, maintenance, and the MIT license

A general HTTP client such as `curl` can send arbitrary requests, but it does not provide xurl's named-app registry, default app and user selection, OAuth flow, persistent YAML configuration, or X-specific enrollment troubleshooting. The trade-off runs in both directions: xurl is more specialized and stores credentials for reuse, while `curl` is the better choice when targeting unrelated services or when request automation should avoid any X-specific state.

The repository is not archived. Its last push was on 2026-09-29, followed by the `v1.3.4` release on 2026-09-29. Earlier listed releases include `v1.3.2` on 2026-09-24 and `v1.3.1` on 2026-07-21. These dates show recent project activity, but they do not by themselves establish compatibility with every X platform change. The dependency on `github.com/xdevplatform/chat-xdk/go/chatxdk v0.4.1` is relevant to `xurl chat`, while ordinary authentication and request behavior also depend on external X platform configuration.

The repository is licensed under MIT. That permits use, modification, distribution, and sublicensing subject to the license terms, including preservation of its copyright and permission notice. This is a project-level statement, not advice about how a particular organization should comply with API terms or protect stored credentials.

Editorial conclusion

Adopt xurl if you need a repeatable, credential-aware command-line path to the X API, especially across multiple apps or users. Do not choose it as a replacement for a general HTTP client because it is focused on X-specific authentication and storage. Before the first production call, verify the app's redirect URI, package, and environment in the X developer console, then confirm the selected default app with `xurl auth status`.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. xdevplatform/xurl on GitHub