{"id":28930315,"url":"https://github.com/xdevplatform/xurl","last_synced_at":"2026-02-20T04:05:31.440Z","repository":{"id":268164215,"uuid":"903505636","full_name":"xdevplatform/xurl","owner":"xdevplatform","description":"OAuth2.0 enabled curl for the X API","archived":false,"fork":false,"pushed_at":"2025-05-08T21:50:42.000Z","size":7008,"stargazers_count":94,"open_issues_count":5,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-22T15:06:00.472Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xdevplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-14T19:15:44.000Z","updated_at":"2025-06-17T07:13:24.000Z","dependencies_parsed_at":"2025-04-16T22:54:25.169Z","dependency_job_id":"1e3733cc-308e-4a0b-8856-a91cc4319d2f","html_url":"https://github.com/xdevplatform/xurl","commit_stats":null,"previous_names":["santiagomed/xurl","xdevplatform/xurl"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/xdevplatform/xurl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdevplatform%2Fxurl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdevplatform%2Fxurl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdevplatform%2Fxurl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdevplatform%2Fxurl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xdevplatform","download_url":"https://codeload.github.com/xdevplatform/xurl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdevplatform%2Fxurl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29639974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"online","status_checked_at":"2026-02-20T02:00:07.535Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-22T15:05:58.711Z","updated_at":"2026-02-20T04:05:26.964Z","avatar_url":"https://github.com/xdevplatform.png","language":"Go","readme":"# xurl - A curl-like CLI Tool for the X API\n\nA command-line tool for interacting with the X (formerly Twitter) API, supporting both OAuth 1.0a and OAuth 2.0 authentication.\n\n## Features\n\n- OAuth 2.0 PKCE flow authentication\n- OAuth 1.0a authentication\n- Multiple OAuth 2.0 account support\n- Persistent token storage\n- HTTP request customization (headers, methods, body)\n\n## Installation\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | sudo bash\n```\n\n\n## Usage\n\n### Authentication\n\nYou must have a developer account and app to use this tool. \n\n#### App authentication:\n```bash\nxurl auth app --bearer-token BEARER_TOKEN\n```\n\n#### OAuth 2.0 User-Context\n**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).\n\n1. Create an app at the [X API developer portal](https://developer.x.com/en/portal/dashboard).\n2. Go to authentication settings and set the redirect URI to `http://localhost:8080/callback`.\n![Setup](./assets/setup.png)\n![Redirect URI](./assets/callback.png)\n3. Set the client ID and secret in your environment variables.\n```env\nexport CLIENT_ID=your_client_id\nexport CLIENT_SECRET=your_client_secret\n```\n4. Get your access keys:\n```bash\nxurl auth oauth2\n```\n#### OAuth 1.0a authentication:\n```bash\nxurl auth oauth1 --consumer-key KEY --consumer-secret SECRET --access-token TOKEN --token-secret SECRET\n```\n\n### Authentication Management\nView authentication status:\n```bash\nxurl auth status\n```\n\nClear authentication:\n```bash\nxurl auth clear --all                       # Clear all tokens\nxurl auth clear --oauth1                    # Clear OAuth 1.0a tokens\nxurl auth clear --oauth2-username USERNAME  # Clear specific OAuth 2.0 token\nxurl auth clear --bearer                    # Clear bearer token\n```\n\n### Making Requests\n\nBasic GET request:\n```bash\nxurl /2/users/me\n```\n\nCustom HTTP method:\n```bash\nxurl -X POST /2/tweets -d '{\"text\":\"Hello world!\"}'\n```\n\nAdd headers:\n```bash\nxurl -H \"Content-Type: application/json\" /2/tweets\n```\n\nSpecify authentication type:\n```bash\nxurl --auth oauth2 /2/users/me\nxurl --auth oauth1 /2/tweets\nxurl --auth app /2/users/me\n```\n\nUse specific OAuth 2.0 account:\n```bash\nxurl --username johndoe /2/users/me\n```\n\n### Streaming Responses\n\nStreaming endpoints (like `/2/tweets/search/stream`) are automatically detected and handled appropriately. The tool will automatically stream the response for these endpoints:\n\n- `/2/tweets/search/stream`\n- `/2/tweets/sample/stream`\n- `/2/tweets/sample10/stream`\n- `/2/tweets/firehose/strea/lang/en`\n- `/2/tweets/firehose/stream/lang/ja`\n- `/2/tweets/firehose/stream/lang/ko`\n- `/2/tweets/firehose/stream/lang/pt`\n\nFor example:\n```bash\nxurl /2/tweets/search/stream\n```\n\nYou can also force streaming mode for any endpoint using the `--stream` or `-s` flag:\n```bash\nxurl -s /2/users/me\n```\n\n### Temporary Webhook Setup\n\n`xurl` can help you quickly set up a temporary webhook URL to receive events from the X API. This is useful for development and testing.\n\n1.  **Start the local webhook server with ngrok:**\n\n    Run the `webhook start` command. This will start a local server and use ngrok to create a public URL that forwards to your local server. You will be prompted for your ngrok authtoken if it's not already configured via the `NGROK_AUTHTOKEN` environment variable.\n\n    ```bash\n    xurl webhook start\n    # Or with a specific port and output file for POST bodies\n    xurl webhook start -p 8081 -o webhook_events.log\n    ```\n\n    The command will output an ngrok URL (e.g., `https://your-unique-id.ngrok-free.app/webhook`). Note this URL.\n\n2.  **Register the webhook with the X API:**\n\n    Use the ngrok URL obtained in the previous step to register your webhook. You'll typically use app authentication for this.\n\n    ```bash\n    # Replace https://your-ngrok-url.ngrok-free.app/webhook with the actual URL from the previous step\n    xurl --auth app /2/webhooks -d '{\"url\": \"\u003cyour ngrok url\u003e\"}' -X POST\n    ```\n\n    Your local `xurl webhook start` server will then handle the CRC handshake from Twitter and log incoming POST events (and write them to a file if `-o` was used).\n\n### Media Upload\n\nThe tool supports uploading media files to the X API using the chunked upload process.\n\nUpload a media file:\n```bash\nxurl media upload path/to/file.mp4\n```\n\nWith custom media type and category:\n```bash\nxurl media upload --media-type image/jpeg --category tweet_image path/to/image.jpg\n```\n\nCheck media upload status:\n```bash\nxurl media status MEDIA_ID\n```\n\nWait for media processing to complete:\n```bash\nxurl media status --wait MEDIA_ID\n```\n\n#### Direct Media Upload\n\nYou can also use the main command with the `-F` flag for direct media uploads:\n\n1. First, initialize the upload:\n```bash\nxurl -X POST '/2/media/upload?command=INIT\u0026total_bytes=FILE_SIZE\u0026media_type=video/mp4\u0026media_catefory=tweet_video'\n```\n\n2. Then, append the media chunks:\n```bash\nxurl -X POST -F path/to/file.mp4 '/2/media/upload?command=APPEND\u0026media_id=MEDIA_ID\u0026segment_index=0'\n```\n\n3. Finally, finalize the upload:\n```bash\nxurl -X POST '/2/media/upload?command=FINALIZE\u0026media_id=MEDIA_ID'\n```\n\n4. Check the status:\n```bash\nxurl '/2/media/upload?command=STATUS\u0026media_id=MEDIA_ID'\n```\n\n## Token Storage\n\nTokens are stored securely in `~/.xurl` in your home directory.\n\n## Contributing\nContributions are welcome!\n\n## License\nThis project is open-sourced under the MIT License - see the LICENSE file for details.","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdevplatform%2Fxurl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdevplatform%2Fxurl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdevplatform%2Fxurl/lists"}