A command-line tool for Twitter and X workflows using the TwitterAPI.io service.
You may need an API key from https://twitterapi.io/ to use many commands. This project is an independent CLI and is not affiliated with TwitterAPI.io.
npm install -g twitterapi-cliOr run without installing:
npx twitterapi-cli --helpYou can also use the compatibility alias if you want the shorter command:
npx twitterapi --helpThis repo now includes a GitHub Actions workflow at:
.github/workflows/publish-npm.yml
How it works:
- bump
package.jsonto the new version - push the commit
- create a GitHub release with tag
v<package-version> - GitHub Actions runs checks, builds, and publishes to npm automatically
Trusted publishing setup:
- configure
twitterapi-clion npmjs.com with a trusted publisher - provider: GitHub Actions
- workflow filename:
publish-npm.yml - this requires GitHub-hosted runners
Important:
- the workflow checks that the GitHub release tag matches
package.json - expected tag format is
v0.1.1,v0.1.2, etc. id-token: writeis enabled so npm can use OIDC trusted publishing- no long-lived
NPM_TOKENsecret is needed once trusted publishing is configured on npm - workflow is pinned to Node 24-compatible action majors:
actions/checkout@v6actions/setup-node@v6pnpm/action-setup@v5
- JSON-first output
- strict TypeScript
- stable command contracts
- latest Node.js LTS baseline
- clear split between API-key reads and login-cookie actions
usertweetlistcommunitytrendspacemyauthdmmediaprofilewebhookstream
twitterapi user batch-info <userIds>twitterapi user info <username>twitterapi user timeline <userId>twitterapi user tweets <username>twitterapi user followers <username>twitterapi user following <username>twitterapi user mentions <username>twitterapi user relationship <sourceUserName> <targetUserName>twitterapi user search <query>twitterapi user verified-followers <userId>twitterapi user about <username>twitterapi user follow <userId>twitterapi user unfollow <userId>
twitterapi tweet get <tweetIds>twitterapi tweet search <query>twitterapi tweet replies <tweetId>twitterapi tweet replies-v2 <tweetId>twitterapi tweet quotes <tweetId>twitterapi tweet retweeters <tweetId>twitterapi tweet thread <tweetId>twitterapi tweet article <tweetId>twitterapi tweet create <text>twitterapi tweet delete <tweetId>twitterapi tweet like <tweetId>twitterapi tweet unlike <tweetId>twitterapi tweet retweet <tweetId>twitterapi tweet bookmark <tweetId>twitterapi tweet unbookmark <tweetId>twitterapi tweet bookmarks
twitterapi list timeline <listId>twitterapi list followers <listId>twitterapi list members <listId>
twitterapi community info <communityId>twitterapi community members <communityId>twitterapi community moderators <communityId>twitterapi community tweets <communityId>twitterapi community search <query>twitterapi community create <name> --description "..."twitterapi community delete <communityId> <communityName>twitterapi community join <communityId>twitterapi community leave <communityId>
twitterapi trend get <woeid>twitterapi space detail <spaceId>twitterapi my info
twitterapi auth whoamitwitterapi auth login --user-name <user> --email <email> --password <password> --proxy <proxy>twitterapi dm send <userId> <text>twitterapi media upload <filePath>twitterapi profile update-avatar <filePath>twitterapi profile update-banner <filePath>twitterapi profile update --name ... --description ...
twitterapi webhook add-rule <tag> <value> --interval-seconds <seconds>twitterapi webhook get-rulestwitterapi webhook update-rule <ruleId> <tag> <value> --interval-seconds <seconds>twitterapi webhook delete-rule <ruleId>twitterapi stream add-user <username>twitterapi stream remove-user <monitorId>twitterapi stream users
To use the service-backed commands, get an API key from https://twitterapi.io/ and provide it through flags, environment variables, or config.
This CLI is an independent open-source project and has no official relationship with TwitterAPI.io, X, or Twitter.
The CLI loads configuration in this order:
- command flags
- environment variables
~/.twitterapi/config.json- built-in defaults
Supported env vars:
TWITTERAPI_KEYTWITTERAPI_BASE_URLTWITTERAPI_TIMEOUT_MSTWITTERAPI_PROXYTWITTERAPI_LOGIN_COOKIES
Example ~/.twitterapi/config.json:
{
"api_key": "***",
"base_url": "https://api.twitterapi.io",
"timeout": 30,
"proxy": "http://user:pass@host:port",
"login_cookies": "base64-or-raw-cookie-string"
}Most read endpoints only need x-api-key.
Write/action endpoints generally need both:
TWITTERAPI_KEYTWITTERAPI_LOGIN_COOKIESTWITTERAPI_PROXY
Get login cookies with:
twitterapi --proxy http://user:pass@host:port auth login \
--user-name your_user \
--email you@example.com \
--password '***'pnpm dev user info elonmusk --compact
pnpm dev user followers elonmusk --page-size 50 --compact
pnpm dev tweet search "openai" --limit 5 --compact
pnpm dev tweet get 1911803830911527103,1911803830911527104 --compact
pnpm dev trend get 1 --count 30
pnpm dev my info
pnpm dev --proxy http://user:pass@host:port auth login --user-name foo --email foo@example.com --password '***'
pnpm dev --login-cookies "$TWITTERAPI_LOGIN_COOKIES" --proxy "$TWITTERAPI_PROXY" tweet create "hello from cli"
pnpm dev --login-cookies "$TWITTERAPI_LOGIN_COOKIES" --proxy "$TWITTERAPI_PROXY" media upload ./image.pngpnpm dev --helppnpm buildpnpm testpnpm lintpnpm typecheckpnpm check
- Output is always JSON or JSONL.
- Compact field filtering is available on many user/tweet list commands via
--compactand--fields. - Some TwitterAPI.io endpoints may report
has_next_page=trueeven when the next page is empty. - Free-tier rate limits are strict; back off a few seconds between live smoke tests.
- TwitterAPI.io docs have a few inconsistencies around
login_cookiesand some v2 naming, so the CLI follows the documented API paths directly.
This repo also ships a distributable skill under:
skills/twitterapi-cli/