Rettiwt-API: a command line and Node library for fetching Twitter data

The problem: the official API is not the only way in

Twitter's paid API tier puts a price and a rate limit in front of most of the data people actually want, and the free tier is narrow. Anyone who has built a scraper, a dashboard or a research pipeline on top of that knows the workaround: use the endpoints the web application itself calls, with a session cookie rather than a bearer token.

Rettiwt-API is a library and command line tool for doing exactly that, and the project describes itself as a CLI tool and an API for fetching data from Twitter for free. The package metadata is blunter still, calling it an API for fetching data from TwitterAPI without any rate limits, which is the kind of claim a reader should treat as a slogan rather than a specification.

The audience is two groups. Developers embedding it in a Node project get a typed class with resource groups for tweets, users, spaces, lists, direct messages and calls. People who are not going to write JavaScript get the CLI, and the documentation goes out of its way to tell them to use it, noting that the CLI provides an easy to use interface which does not require any knowledge of JavaScript or programming.

The project is TypeScript, published as rettiwt-api on npm, with a version of 7.1.4, a documentation site hosted as a GitHub Pages project, and a last push on 2026-10-19. The releases are 7.1.4 from 2026-09-26, 7.1.3 from 2026-08-07 and 7.1.2 from 2026-06-23, so it is moving regularly, and the default branch is dev rather than master.

Two authentication tiers, and only four things a guest can do

The authentication model is the design decision that matters, because it determines both what you can call and what you are agreeing to when you call it.

There are two strategies. Guest authentication means not logging in, and it grants access to a deliberately small set of resources: tweet details, space details, user details by username, and the user timeline. User authentication means logging in, and it grants access to everything else plus everything the guest tier allows.

Guest authentication is the default. That is a sensible default for a library, because a program that fetches a public tweet should not need an account, and a developer evaluating the library can run it without handing over credentials.

User authentication is where the care is needed. It is implemented by taking the cookies associated with your Twitter account and encoding them into an API_KEY, and the documentation is unusually blunt about the consequences: the API_KEY provides the same level of authorization as any standard Twitter account, nothing more, nothing less.

That sentence is the whole risk model in one line. There is no scope, no permission set, no read-only mode. A key generated this way can do anything the account can do, including the things you would not want an automated script to do. Any project you write with it inherits that, whether or not your code touches the destructive endpoints.

The class also accepts a proxy parameter, typed as a string or an AxiosProxyConfig, which is the escape hatch for networks where direct connections are not an option.

The API_KEY is a base64 cookie string, and that is the entire security story

It is worth being precise about what the API_KEY is, because the documentation says it plainly and most users skim past it.

The API_KEY is a base64 encoding of the account's cookies. The cookies in question are three fields, auth_token, ct0 and twid, and the base64 string is produced by concatenating them in that order with semicolons. The documentation includes the exact browser command that does the encoding, so you can see the whole mechanism rather than guessing at it:

btoa("auth_token=<auth_token_value>;ct0=<ct0_value>;twid=<twid_value>;")

Base64 is an encoding, not encryption. Anyone who can see the key can decode it in a second and read your session cookies, which is why the documentation insists that the key is very sensitive information and must be stored securely.

The practical consequences for an adopter are straightforward. The key belongs in a secret store or an environment variable, never in a committed file. It should never be pasted into a chat, an issue tracker or a log. If it leaks, the correct response is not to regenerate it but to change the account credentials, because the key stops working when the credentials change.

The documentation also notes the lifetime, which is unusual to see stated: an API_KEY created this way should last 5 years from the date of login, as long as the credentials to the account are not changed.

Three ways to get a key, and why the browser-based ones are fragile

The documentation offers three routes to an API_KEY, and they differ in how much they trust your browser session to survive.

The manual method is the most transparent. You open the developer tools with F12, navigate to the cookies storage for your browser, copy the values of auth_token, ct0 and twid, and run the btoa command in the console. Nothing third party is involved, and the cost is that you are pasting a live credential into a console and handling it by hand.

The ScriptCat route uses a third-party userscript, the Rettiwt API Key Generator, which needs the ScriptCat userscript manager installed, and then reads the login cookies from x.com or twitter.com. The documentation flags it as a third-party userscript that is not part of Rettiwt-API, which is the right flag to raise about a tool that reads your session cookies.

The Firefox extension route installs the Rettiwt Auth Helper from Firefox Add-ons and requires it to be allowed to run in private mode. You switch to private mode, log in, and press Get API Key in the extension popup.

The private mode instruction is the clever part, and the documentation explains why. A key derived from a normal session is revoked the moment you log out, because logging out invalidates the cookies. A key derived from a private-mode session survives the session ending, since the browser forgets the login but the key stays valid, until the credentials themselves change or five years pass. So the same operation gives you a key that lasts minutes or one that lasts years, depending on whether you used private mode.

All three routes are browser-dependent, which is the underlying fragility. A browser update that changes the cookie storage, or a change on the platform side, can break all of them at once.

The Rettiwt class: one entry point and six resource groups

When the package is used as a dependency, the entry point is the Rettiwt class, and construction decides the authentication tier:

const rettiwt = new Rettiwt()

for guest access, and:

const rettiwt = new Rettiwt({ apiKey: API_KEY })

for user access, with the key you generated.

From there, the API is organised by resource rather than by endpoint. The documentation lists members for calls, direct messages, lists, spaces, tweets and users, and the features section of the site is where the individual methods are described. Grouping by resource is the right shape for a wrapper of this size: a method called listTweets or a namespace of tweet methods keeps the surface navigable in a way that a flat list of two hundred endpoint functions would not.

There is a small documentation slip worth knowing about, because it will confuse you the first time you read it. The text says the Rettiwt class has five members, and then lists six of them, with direct messages among them. Trust the list.

The project also notes that when the package is installed locally in your project, the CLI commands have to be prefixed with npx, so that NodeJS uses the locally installed package rather than any global one.

Installing: a global CLI, or a local dependency with npx

The installation is documented for two audiences, and the CLI is the one the documentation pushes first.

For command line use, the recommendation is to install the package globally. The steps are to open a terminal, install the package, and then check that it is installed correctly:

npm install -g rettiwt-api

rettiwt help

The verification step is the one people skip, and it is worth doing, because a global install that silently fails looks exactly like a working install with a missing command.

For use inside your own project, you install it locally as a dependency instead, with npm or with yarn:

npm install --save rettiwt-api

yarn add rettiwt-api

and you prepend npx to the CLI commands so that the local copy is the one that runs.

The prerequisites are NodeJS 22 or 24, and a working Twitter account, which the documentation marks as optional because guest authentication does not need one. The package metadata is more precise than that: the engines field requires Node ^22.21.0 or ^24.0.0, and there is a .nvmrc file in the repository, so the version is pinned rather than left to chance.

The repository layout is conventional for a TypeScript package: src/ for the source, a playground/ directory for experiments, an eslint configuration in two forms, a prettier configuration, a tsconfig.json and a package-lock.json. The build script is tsc, the documentation is generated with typedoc excluding private, protected and internal members, and the lint script runs eslint with warnings treated as errors.

Licence metadata that disagrees with itself, and where this is the wrong tool

There is a discrepancy in this repository that a reader should resolve before shipping anything with it. The licence recorded for the repository is MIT, and the repository root carries a LICENSE file, while the package metadata in package.json declares the licence as ISC. Those are two different licences with different terms, and the one that matters for most consumers is the one in the published package.

There is a second, smaller inconsistency in the same file. The repository url points at a different project path, Rishikant181/twitter-api.git, and the package description claims there are no rate limits, which is a promotional claim rather than a documented property of the code.

Neither of these is fatal, and both are fixable by the maintainer. But they are the kind of detail that suggests the packaging metadata is not being kept in step with the repository, which is worth weighing against the fact that the code itself is well documented.

As for when this is the wrong tool, the honest answer is about the account model rather than the code. If your requirement is scoped, read-only access to a small set of public data, a guest-mode script that never holds a credential is a much better position to be in, and this library supports it. If you need the full endpoint set, you are running a logged-in session with full account authority, and you have to accept the platform's terms as well as the security burden of the key.

And if what you actually need is a supported, contracted data feed with rate limits you can plan around, this is the wrong shape of tool. The library exists precisely because the official route is not available for many users, and that is a legitimate reason to use it and a reason to be careful with it.

Editorial conclusion

Adopt Rettiwt-API if you need read access to Twitter data from Node or a shell, either anonymously for tweets, spaces, users by name and timelines, or with your own account for the rest. Do not adopt it as a long lived production dependency without reading the account rules, because it authenticates with your real session cookies rather than a scoped token. Before you rely on it, settle the licence question, since the repository and the package metadata name different licences, and check the guest versus user boundary against the endpoints you actually need, since the guest tier covers only four resource groups.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Rishikant181/Rettiwt-API on GitHub