Apollo CLI: what the apollo-tooling monorepo still does in 2026

The problem Apollo CLI was built to solve

A GraphQL client is only as correct as its queries. Nothing in the GraphQL specification stops you from writing a selection set that names a field the server does not expose, or from omitting a required argument, and the failure only appears at runtime. Apollo CLI was built to close that gap from the client side. The README describes it as bringing together GraphQL clients and servers with tools for validating your schema, linting your operations for compatibility with your server, and generating static types for improved client-side type safety.

The audience was teams running a client in TypeScript, Flow or Swift against a GraphQL endpoint, usually one registered in Apollo's registry. Those teams wanted a build step that fails when a query drifts from the schema. The commands split along that line. apollo client:check validates a client project against a pushed service. apollo client:codegen generates static types. apollo client:download-schema and apollo client:extract pull the schema down. apollo client:push sends operation information up. The apollo service:* family handled the server side of the registry.

That scope is also why the project is winding down. The README carries a note dated 2022-01-21 stating that Apollo is working towards fully deprecating the repository and that most of its functionality has been replaced by newer projects. Support for the tooling is described as minimal.

How the client commands fit together

The mechanism is a config file plus a schema source. The repository root contains apollo.config.js, and every client command accepts a -c, --config flag pointing at an Apollo config file. The --graph and --variant flags override the config file when set, which is how a single checkout can target different graphs or variants without editing the file.

Schema resolution has two paths. The CLI can introspect a live endpoint, which is what the --endpoint flag is for, or it can read a schema that was downloaded earlier with apollo client:download-schema. The README notes that --header may be repeated to add multiple headers during introspection and that --endpoint is required when using --header. That constraint matters for anyone hitting a gateway behind an authorization layer.

Operation discovery is glob based. The --includes flag takes a glob to search for GraphQL operations, and the README says it should be used to find queries and any client schema extensions. The --excludes flag takes a glob of files to skip, with an explicit caveat in the README that it does not currently work in watch mode. The --tagName flag names the template literal tag used to identify GraphQL queries in JavaScript or TypeScript code, so a codebase using a custom gql alias can still be scanned.

Generated output goes where the OUTPUT argument says. The README is precise about the variation: for TypeScript and Flow generators the argument is a directory relative to each source file by default, but with the outputFlat flag it becomes a file or directory relative to the working directory, and for the Swift generator it is always a file or directory. All other targets write a single file. The --[no-]addTypename flag controls whether __typename is added automatically, and it defaults to true.

Installing the Apollo CLI and running a first codegen pass

The README's usage section gives the install as a global npm package, followed by the command and a version check. The example output in the README shows apollo/2.33.11 on darwin-arm64 with node-v16.14.2, which is a useful hint about the Node range the tool was exercised against.

npm install -g apollo
apollo --help

After the install, apollo --help prints the command list. The README's own command index lists client commands (check, codegen, download-schema, extract, push), help, the plugins family, and the service commands (check, delete, download, list, push).

A first real use is generating TypeScript types for the queries in a source directory. The repository's own package.json runs codegen this way, targeting typescript with outputFlat and writing to a single file.

apollo client:codegen --target=typescript --outputFlat ./src/graphqlTypes.ts

What you should see is that file created or rewritten with the generated types for the operations the CLI found. If the CLI cannot resolve a schema, the run fails before writing, which is the intended behaviour rather than a silent skip. To generate per-file output instead, drop --outputFlat and pass a directory; the README states that for TypeScript and Flow generators the directory is interpreted relative to each source file.

One environment note from the repository: the root package.json declares engines of node >=8 <17 and npm >=8.5.0 <9.x, and there is a script named install-with-npm-8.5 that installs npm@^8.5.0 before running npm i. That is the maintainers' own workaround for the npm range.

Where Apollo CLI stops being the right tool

The strongest limitation is stated by the project itself. The README carries a note dated 2022-07-07 telling readers who came for codegen to use graphql-code-generator instead, adding that codegen in this repository is no longer supported and will be removed completely in a future version. A deprecation notice that direct is not a nuance. If type generation is the only reason you are looking at this repository, the README redirects you elsewhere.

The second limitation is the service commands. A note dated 2023-03-29 states that all apollo service:* commands reach end-of-life on April 28th, 2023. Running them against the registry is not a supported path now.

The third is narrower but will bite in practice: the README documents that --excludes does not work in watch mode. A team relying on watch-driven validation with an exclusion list will find the exclusions ignored during that loop.

There is also a maintenance signal in the release history. The most recent release listed is [email protected] from 2022-05-20. The repository is not archived and the last push was on 2026-09-23, so the tree is not frozen, but the published CLI has not had a release in years. Treat the npm package and the repository as two different things: activity in the monorepo does not imply a new apollo binary.

graphql-code-generator as the replacement the README points to

The difference is architectural, not cosmetic. Apollo CLI shipped one opinionated pipeline: an Apollo config file, a target flag, and generators for TypeScript, Flow and Swift inside the same binary. graphql-code-generator is built around a plugin model, where schema inputs and output generators are separate plugins you compose in a config file. That means you can target languages and shapes Apollo CLI never covered without waiting for the CLI to add a generator, and you are not tied to Apollo's registry as the schema source.

The migration cost is real. Anything encoded in apollo.config.js has to be expressed again in the other tool's config format, and the --tagName, --includes and --excludes behaviour has to be reproduced through that tool's document discovery settings. The README links a writeup by @dotansimha in issue 2053 for migration details, which is the place to look before rewriting a build step.

For teams that only ever used apollo client:check, the comparison is less clean. The check command validates operations against a pushed service, which is a registry-coupled workflow. Replacing it usually means moving validation into CI against a schema artifact rather than a registry variant, which is a different design decision rather than a drop-in swap.

Licence, maintenance and what an upgrade actually costs

The repository is MIT licensed, and the README's badge links to the LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice preserved. That is a statement about the licence text, not legal advice, and it says nothing about the deprecation notices, which are a support question rather than a licensing one. The practical implication is that you can keep a vendored or forked copy of the CLI alive if you need to, provided you keep the notice.

Upgrade cost is dominated by the deprecations rather than by version drift. The CLI's last listed release is [email protected] from 2022-05-20, so there is no steady stream of upgrades to absorb. The cost sits in two places. First, codegen will be removed in a future version, so any build that calls apollo client:codegen has a deadline attached to it. Second, the service commands already reached end-of-life on April 28th, 2023, so pipelines that call them are running something the project no longer supports.

The repository itself is a TypeScript monorepo built with tsc --build and tested with jest, with changesets driving releases through the changeset-publish script. If you are building from source rather than installing the npm package, note the engines constraint and the postinstall hook, which runs npm run build automatically after install.

Editorial conclusion

Adopt Apollo CLI only for existing projects that already depend on its config file and commands, and only after checking the end-of-life note for apollo service:* commands and the deprecation notice on codegen. New projects should start with a maintained replacement rather than this repository, since the README states that codegen is no longer supported and most functionality has been replaced. Before committing, run apollo client:codegen against your own schema and verify that the generated types match what your client imports, because the README does not document a rollback path for the removal of codegen in a future version.

Frequently asked questions

Official sources

1. apollographql/apollo-tooling on GitHub
2. License: MIT
3. Project website
4. README
5. Releases