{"id":50308141,"url":"https://github.com/nicshik/tweet-api-skill","last_synced_at":"2026-05-28T18:01:51.461Z","repository":{"id":355562888,"uuid":"1217693866","full_name":"nicshik/tweet-api-skill","owner":"nicshik","description":"Portable Codex skill and CLI helpers for reading X/Twitter data through twitterapi.io","archived":false,"fork":false,"pushed_at":"2026-05-04T08:22:40.000Z","size":64,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T09:35:59.630Z","etag":null,"topics":["agent-tools","api-client","cli-tool","codex-skill","python","research","social-media-research","twitter","twitterapi-io","x-twitter"],"latest_commit_sha":null,"homepage":"https://docs.twitterapi.io/","language":"Python","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/nicshik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T06:04:33.000Z","updated_at":"2026-05-04T08:22:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nicshik/tweet-api-skill","commit_stats":null,"previous_names":["nicshik/tweet-api-skill"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nicshik/tweet-api-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicshik%2Ftweet-api-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicshik%2Ftweet-api-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicshik%2Ftweet-api-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicshik%2Ftweet-api-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicshik","download_url":"https://codeload.github.com/nicshik/tweet-api-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicshik%2Ftweet-api-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33619972,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":["agent-tools","api-client","cli-tool","codex-skill","python","research","social-media-research","twitter","twitterapi-io","x-twitter"],"created_at":"2026-05-28T18:01:51.292Z","updated_at":"2026-05-28T18:01:51.451Z","avatar_url":"https://github.com/nicshik.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TwitterAPI X Reader\n\n[![CI](https://github.com/nicshik/tweet-api-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/nicshik/tweet-api-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nPortable skill and helper scripts for working with X (Twitter) through `twitterapi.io`.\n\n[🇷🇺 Читать на русском](README.ru.md)\n\n## Overview\n\nThis repository packages a reusable skill plus terminal helpers for reading tweets, X Articles, downloading tweet videos, and calling other documented `twitterapi.io` endpoints without relying on direct `x.com` rendering.\n\nIt is designed for people who want:\n\n- a portable skill install in `~/.codex/skills/twitterapi-x-reader`;\n- simple terminal commands like `xread`, `xapi`, and `xmedia`;\n- a stable path for research, summarization, and structured extraction from X.\n\nThis project is not affiliated with X Corp., Twitter, or `twitterapi.io`.\n\nMaintainer: [`nicshik`](https://github.com/nicshik).\n\n## What Is Included\n\n- `SKILL.md` for agent environments that support skill-style workflows\n- `agents/openai.yaml` for UI metadata\n- `references/` with quickstart, human-readable notes, and research examples\n- `scripts/` with Python helpers\n- `bin/xread`, `bin/xapi`, and `bin/xmedia` terminal wrappers\n- `install_portable.sh` for install and update\n\n## Requirements\n\n- Python 3.10 or newer\n- `zsh`, `rsync`, and `install` for `install_portable.sh`\n- a `twitterapi.io` API key\n\n## Installation\n\n### Portable Skill Install\n\nFrom the repository root:\n\n```bash\nchmod +x ./install_portable.sh\n./install_portable.sh\n```\n\nThen create your local key file if it does not already exist:\n\n```bash\nmkdir -p ~/.codex/skills/twitterapi-x-reader\nprintf '%s\\n' 'TWITTERAPI_IO_KEY=your_key_here' \u003e ~/.codex/skills/twitterapi-x-reader/.env.local\n```\n\nIf your shell does not already include `~/.local/bin` in `PATH`, add it.\n\n### CLI Package Install\n\nIf you only need the `xread`, `xapi`, and `xmedia` console scripts, install the package directly:\n\n```bash\npython -m pip install \"git+https://github.com/nicshik/tweet-api-skill.git\"\n```\n\nThe package install does not install the Codex skill files. Use `TWITTERAPI_IO_KEY` or `--api-key` for authentication.\n\n## Quick Start\n\nFetch a tweet or article:\n\n```bash\nxread \"https://x.com/ZenithTON/status/2046570503801119055\"\n```\n\nForce article mode:\n\n```bash\nxread \"2046570503801119055\" --mode article\n```\n\nDownload the best MP4 video from a tweet:\n\n```bash\nxmedia \"https://x.com/Yoda4ever/status/2049680135658336270?s=20\" --output-dir ./downloads\n```\n\n`xmedia` prints JSON with the saved file path, byte count, source media URL, bitrate, and media key. Downloads are limited to HTTPS URLs under `video.twimg.com`.\n\nCall any documented endpoint:\n\n```bash\nxapi --method GET --path /oapi/my/info --query-json '{}'\n```\n\n`xapi` accepts official API paths by default. Full URLs are only accepted for `https://api.twitterapi.io` so the API key is not sent to arbitrary hosts.\n\nMutating HTTP methods are blocked unless you pass `--allow-mutation`:\n\n```bash\nxapi --method POST --path /twitter/post/create --body-json '{\"text\":\"draft\"}' --allow-mutation\n```\n\n## Video Downloads\n\nFor an installed skill, video export is initiated with the global wrapper:\n\n```bash\nxmedia \"\u003ctweet-url-or-id\u003e\" --output-dir ./downloads\n```\n\nThe direct skill-script equivalent is:\n\n```bash\npython3 ~/.codex/skills/twitterapi-x-reader/scripts/twitterapi_media.py \"\u003ctweet-url-or-id\u003e\" --output-dir ./downloads\n```\n\nThe command writes one or more `.mp4` files and prints JSON like:\n\n```json\n{\n  \"kind\": \"media_download\",\n  \"tweet_id\": \"2049680135658336270\",\n  \"files\": [\n    {\n      \"path\": \"/absolute/path/to/2049680135658336270-media-1-2176000.mp4\",\n      \"bytes\": 5744965,\n      \"bitrate\": 2176000,\n      \"media_key\": \"13_2049617901142118400\",\n      \"url\": \"https://video.twimg.com/...\"\n    }\n  ],\n  \"source\": \"twitterapi.io\"\n}\n```\n\nUseful flags:\n\n- `--output-dir ./downloads` sets the destination directory.\n- `--first` downloads only the first video media item.\n- `--filename name.mp4` sets the output name when exactly one file is selected.\n- `--overwrite` replaces an existing file.\n\n## Practical Workflows\n\nRead a tweet or X Article and then analyze it:\n\n```bash\nxread \"https://x.com/ZenithTON/status/2046570503801119055\"\n```\n\nLook up the author profile:\n\n```bash\nxapi --method GET --path /twitter/user/info --query-json '{\"userName\":\"ZenithTON\"}'\n```\n\nPull the author's recent tweets:\n\n```bash\nxapi --method GET --path /twitter/user/last_tweets --query-json '{\"userName\":\"ZenithTON\",\"includeReplies\":false}'\n```\n\nInspect replies:\n\n```bash\nxapi --method GET --path /twitter/tweet/replies/v2 --query-json '{\"tweetId\":\"2046570503801119055\",\"queryType\":\"Latest\"}'\n```\n\nInspect quote tweets:\n\n```bash\nxapi --method GET --path /twitter/tweet/quotes --query-json '{\"tweetId\":\"2046570503801119055\",\"includeReplies\":false}'\n```\n\nSearch accounts by topic:\n\n```bash\nxapi --method GET --path /twitter/user/search --query-json '{\"query\":\"TON AI\"}'\n```\n\nSearch tweets by topic:\n\n```bash\nxapi --method GET --path /twitter/tweet/advanced_search --query-json '{\"query\":\"\\\"AI agents\\\" Telegram TON\",\"queryType\":\"Top\"}'\n```\n\nDownload tweet video media for later processing:\n\n```bash\nxmedia \"https://x.com/Yoda4ever/status/2049680135658336270?s=20\" --output-dir ./downloads --overwrite\n```\n\nIf a tweet has several video media items, `xmedia` downloads all of them by default. Use `--first` to download only the first item, or `--filename custom-name.mp4` when exactly one item is selected.\n\nFor more detailed examples, see:\n\n- `references/research_examples.md`\n- `references/capabilities.md`\n- `references/api_quickstart.md`\n- `references/endpoint_catalog.md`\n\n## API Key Handling\n\nThis repository does not store API keys.\n\nThe expected local key file is:\n\n```text\n~/.codex/skills/twitterapi-x-reader/.env.local\n```\n\nExample:\n\n```text\nTWITTERAPI_IO_KEY=your_key_here\n```\n\nThe scripts also accept `--api-key`, but environment variables or `.env.local` are preferred because command-line arguments can be recorded in shell history.\n\n## Development\n\nRun the no-network tests:\n\n```bash\npython -m unittest discover -s tests\n```\n\nCheck local documentation links:\n\n```bash\npython scripts/check_links.py\n```\n\nVerify the package entry points locally:\n\n```bash\npython -m pip install .\nxapi --help\nxread --help\nxmedia --help\n```\n\nValidate the skill metadata with the Skill Creator validator when available:\n\n```bash\npython /path/to/skill-creator/scripts/quick_validate.py .\n```\n\n## Support / Security\n\nUse GitHub Issues for questions, bugs, and feature requests.\n\nReport security vulnerabilities privately through `SECURITY.md`. Do not open public issues with API keys, `.env.local`, private account data, or exploit details.\n\n## Update Flow\n\nAfter pulling new changes from this repository, refresh the portable install with:\n\n```bash\n./install_portable.sh\n```\n\nThis updates the installed skill and global wrappers while preserving the local `.env.local` file.\n\nOlder local installs under `~/.codex/skills/twitterapi_x_reader` are detected during installation. The installer copies the legacy `.env.local` into the new hyphen-case skill directory when needed, and the `xread`/`xapi`/`xmedia` wrappers still check the legacy path for compatibility.\n\n## Notes\n\n- The default posture is read-only.\n- Mutating API endpoints should only be used intentionally.\n- Media downloads write local files and are limited to `video.twimg.com`.\n- `certifi` is supported when available, but the scripts can also fall back to the system certificate store.\n- See `SECURITY.md` before publishing logs, examples, or bug reports.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicshik%2Ftweet-api-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicshik%2Ftweet-api-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicshik%2Ftweet-api-skill/lists"}