ng-apollo
v2.36.8
Published
Command line tool for Apollo GraphQL
Downloads
4
Readme
Apollo CLI
[2023-03-29] Note - all
apollo service:*
commands will reach end-of-life on April 28th, 2023. Refer to this blog post for more details.
[2022-07-07] Are you here for codegen? We highly recommend using graphql-code-generator instead. Codegen in this repo is no longer supported and will be removed completely in a future version. For additional migration details, please see this fantastic writeup by @dotansimha: https://github.com/BrendanEthika/apollo-tooling/issues/2053
[2022-01-21] Note - Upcoming Deprecation Plans: We (Apollo) are working towards fully deprecating this repository and its related projects. Most of the functionality in this repository has been replaced by newer projects and the rest will be soon. We'll share detailed migration documentation when everything here is ready to be officially deprecated, but just a heads up in case you're planning on adopting anything here for a new project (which you still can of course if the tooling here works for you - support for this tooling will be minimal however).
[2021-07-23] Note - Housekeeping: Apollo's GraphQL VSCode extension is no longer housed in this repository. It is now maintained separately in this repo.
Apollo CLI brings together your 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.
Usage
Disclaimer: The following API documentation is only for the latest version released on NPM, and may not be accurate for previous or future versions.
$ npm install -g ng-apollo
$ apollo COMMAND
running command...
$ apollo (-v|--version|version)
ng-apollo/2.36.7 darwin-arm64 node-v20.11.0
$ apollo --help [COMMAND]
USAGE
$ apollo COMMAND
...
Commands
apollo client:check
apollo client:download-schema OUTPUT
apollo client:extract OUTPUT
apollo client:push
apollo help [COMMAND]
apollo plugins
apollo plugins:inspect PLUGIN...
apollo plugins:install PLUGIN...
apollo plugins:link PLUGIN
apollo plugins:uninstall PLUGIN...
apollo plugins:update
apollo service:check
apollo service:delete
apollo service:download OUTPUT
apollo service:list
apollo service:push
apollo client:check
Check a client project against a pushed service
USAGE
$ apollo client:check
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID for the graph in Apollo to operate client commands with.
Overrides config file if set.
-v, --variant=variant
The variant of the graph in Apollo to associate this client to
--clientName=clientName
Name of the client that the queries will be attached to
--clientReferenceId=clientReferenceId
Reference id for the client which will match ids from client traces,
will use clientName if not provided
--clientVersion=clientVersion
The version of the client that the queries will be attached to
--endpoint=endpoint
The URL for the CLI use to introspect your service
--excludes=excludes
Glob of files to exclude for GraphQL operations. Caveat: this doesn't
currently work in watch mode
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--includes=includes
Glob of files to search for GraphQL operations. This should be used to
find queries *and* any client schema extensions
--key=key
The API key to use for authentication to Apollo
--queries=queries
Deprecated in favor of the includes flag
--tagName=tagName
Name of the template literal tag used to identify template literals
containing GraphQL queries in Javascript/Typescript code
See code: src/commands/client/check.ts
apollo client:download-schema OUTPUT
Download a schema from Apollo or a GraphQL endpoint in JSON or SDL format
USAGE
$ apollo client:download-schema OUTPUT
ARGUMENTS
OUTPUT [default: schema.json] Path to write the introspection result
to. Can be `.graphql`, `.gql`, `.graphqls`, or `.json`
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID for the graph in Apollo to operate client commands with.
Overrides config file if set.
-v, --variant=variant
The variant of the graph in Apollo to associate this client to
--clientName=clientName
Name of the client that the queries will be attached to
--clientReferenceId=clientReferenceId
Reference id for the client which will match ids from client traces,
will use clientName if not provided
--clientVersion=clientVersion
The version of the client that the queries will be attached to
--endpoint=endpoint
The URL for the CLI use to introspect your service
--excludes=excludes
Glob of files to exclude for GraphQL operations. Caveat: this doesn't
currently work in watch mode
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--includes=includes
Glob of files to search for GraphQL operations. This should be used to
find queries *and* any client schema extensions
--key=key
The API key to use for authentication to Apollo
--queries=queries
Deprecated in favor of the includes flag
--tagName=tagName
Name of the template literal tag used to identify template literals
containing GraphQL queries in Javascript/Typescript code
See code: src/commands/client/download-schema.ts
apollo client:extract OUTPUT
Extract queries from a client
USAGE
$ apollo client:extract OUTPUT
ARGUMENTS
OUTPUT [default: manifest.json] Path to write the extracted queries to
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID for the graph in Apollo to operate client commands with.
Overrides config file if set.
-v, --variant=variant
The variant of the graph in Apollo to associate this client to
--clientName=clientName
Name of the client that the queries will be attached to
--clientReferenceId=clientReferenceId
Reference id for the client which will match ids from client traces,
will use clientName if not provided
--clientVersion=clientVersion
The version of the client that the queries will be attached to
--endpoint=endpoint
The URL for the CLI use to introspect your service
--excludes=excludes
Glob of files to exclude for GraphQL operations. Caveat: this doesn't
currently work in watch mode
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--includes=includes
Glob of files to search for GraphQL operations. This should be used to
find queries *and* any client schema extensions
--key=key
The API key to use for authentication to Apollo
--preserveStringAndNumericLiterals
Disable redaction of string and numerical literals. Without this
flag, these values will be replaced with empty strings (`''`) and
zeroes (`0`) respectively. This redaction is intended to avoid
inadvertently outputting potentially personally identifiable
information (e.g. embedded passwords or API keys) into operation
manifests
--queries=queries
Deprecated in favor of the includes flag
--tagName=tagName
Name of the template literal tag used to identify template literals
containing GraphQL queries in Javascript/Typescript code
See code: src/commands/client/extract.ts
apollo client:push
Register operations with Apollo, adding them to the safelist
USAGE
$ apollo client:push
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID for the graph in Apollo to operate client commands with.
Overrides config file if set.
-v, --variant=variant
The variant of the graph in Apollo to associate this client to
--clientName=clientName
Name of the client that the queries will be attached to
--clientReferenceId=clientReferenceId
Reference id for the client which will match ids from client traces,
will use clientName if not provided
--clientVersion=clientVersion
The version of the client that the queries will be attached to
--endpoint=endpoint
The URL for the CLI use to introspect your service
--excludes=excludes
Glob of files to exclude for GraphQL operations. Caveat: this doesn't
currently work in watch mode
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--includes=includes
Glob of files to search for GraphQL operations. This should be used to
find queries *and* any client schema extensions
--key=key
The API key to use for authentication to Apollo
--queries=queries
Deprecated in favor of the includes flag
--tagName=tagName
Name of the template literal tag used to identify template literals
containing GraphQL queries in Javascript/Typescript code
See code: src/commands/client/push.ts
apollo help [COMMAND]
Display help for apollo.
USAGE
$ apollo help [COMMAND]
ARGUMENTS
COMMAND Command to show help for.
OPTIONS
-n, --nested-commands Include all nested commands in the output.
See code: @oclif/plugin-help
apollo plugins
List installed plugins.
USAGE
$ apollo plugins
OPTIONS
--core Show core plugins.
EXAMPLE
$ apollo plugins
See code: @oclif/plugin-plugins
apollo plugins:inspect PLUGIN...
Displays installation properties of a plugin.
USAGE
$ apollo plugins:inspect PLUGIN...
ARGUMENTS
PLUGIN [default: .] Plugin to inspect.
OPTIONS
-h, --help Show CLI help.
-v, --verbose
EXAMPLE
$ apollo plugins:inspect myplugin
See code: @oclif/plugin-plugins
apollo plugins:install PLUGIN...
Installs a plugin into the CLI.
USAGE
$ apollo plugins:install PLUGIN...
ARGUMENTS
PLUGIN Plugin to install.
OPTIONS
-f, --force Run yarn install with force flag.
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Can be installed from npm or a git url.
Installation of a user-installed plugin will override a core plugin.
e.g. If you have a core plugin that has a 'hello' command, installing a
user-installed plugin with a 'hello' command will override the core
plugin implementation. This is useful if a user needs to update core
plugin functionality in the CLI without the need to patch and update the
whole CLI.
ALIASES
$ apollo plugins:add
EXAMPLES
$ apollo plugins:install myplugin
$ apollo plugins:install https://github.com/someuser/someplugin
$ apollo plugins:install someuser/someplugin
See code: @oclif/plugin-plugins
apollo plugins:link PLUGIN
Links a plugin into the CLI for development.
USAGE
$ apollo plugins:link PLUGIN
ARGUMENTS
PATH [default: .] path to plugin
OPTIONS
-h, --help Show CLI help.
-v, --verbose
DESCRIPTION
Installation of a linked plugin will override a user-installed or core
plugin.
e.g. If you have a user-installed or core plugin that has a 'hello'
command, installing a linked plugin with a 'hello' command will override
the user-installed or core plugin implementation. This is useful for
development work.
EXAMPLE
$ apollo plugins:link myplugin
See code: @oclif/plugin-plugins
apollo plugins:uninstall PLUGIN...
Removes a plugin from the CLI.
USAGE
$ apollo plugins:uninstall PLUGIN...
ARGUMENTS
PLUGIN plugin to uninstall
OPTIONS
-h, --help Show CLI help.
-v, --verbose
ALIASES
$ apollo plugins:unlink
$ apollo plugins:remove
See code: @oclif/plugin-plugins
apollo plugins:update
Update installed plugins.
USAGE
$ apollo plugins:update
OPTIONS
-h, --help Show CLI help.
-v, --verbose
See code: @oclif/plugin-plugins
apollo service:check
[DEPRECATED] Check a service against known operation workloads to find breaking changes
USAGE
$ apollo service:check
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID of the graph in Apollo to check your proposed schema changes
against. Overrides config file if set.
-v, --variant=variant
The variant to check the proposed schema against
--author=author
The author to associate with this proposed schema
--branch=branch
The branch name to associate with this check
--commitId=commitId
The SHA-1 hash of the commit to associate with this check
--endpoint=endpoint
The URL for the CLI use to introspect your service
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--ignoreFailures
Exit with status 0 when the check completes, even if errors are found
--json
Output result in json, which can then be parsed by CLI tools such as
jq.
--key=key
The API key to use for authentication to Apollo
--localSchemaFile=localSchemaFile
Path to one or more local GraphQL schema file(s), as introspection
result or SDL. Supports comma-separated list of paths (ex.
`--localSchemaFile=schema.graphql,extensions.graphql`)
--markdown
Output result in markdown.
--queryCountThreshold=queryCountThreshold
Minimum number of requests within the requested time window for a
query to be considered.
--queryCountThresholdPercentage=queryCountThresholdPercentage
Number of requests within the requested time window for a query to be
considered, relative to total request count. Expected values are
between 0 and 0.05 (minimum 5% of total request volume)
--serviceName=serviceName
Provides the name of the implementing service for a federated graph.
This flag will indicate that the schema is a partial schema from a
federated service
--validationPeriod=validationPeriod
The size of the time window with which to validate the schema against.
You may provide a number (in seconds), or an ISO8601 format duration
for more granularity (see:
https://en.wikipedia.org/wiki/ISO_8601#Durations)
DESCRIPTION
-----------------------------------------------------------------
DEPRECATED: This command will be removed from the `ng-apollo` CLI in
its next major version. Replacement functionality is available in
the new Apollo Rover CLI: https://go.apollo.dev/t/migration
-----------------------------------------------------------------
ALIASES
$ apollo schema:check
See code: src/commands/service/check.ts
apollo service:delete
[DEPRECATED] Delete a federated service from Apollo and recompose remaining services
USAGE
$ apollo service:delete
OPTIONS
-c, --config=config Path to your Apollo config file
-g, --graph=graph The ID of the graph in Apollo for which to
delete an implementing service. Overrides
config file if set.
-v, --variant=variant The variant to delete the implementing
service from
-y, --yes Bypass confirmation when deleting a service
--endpoint=endpoint The URL for the CLI use to introspect your
service
--header=header Additional header to send during
introspection. May be used multiple times to
add multiple headers. NOTE: The `--endpoint`
flag is REQUIRED if using the `--header`
flag.
--key=key The API key to use for authentication to
Apollo
--serviceName=serviceName (required) Provides the name of the
implementing service for a federated graph
DESCRIPTION
-----------------------------------------------------------------
DEPRECATED: This command will be removed from the `ng-apollo` CLI in
its next major version. Replacement functionality is available in
the new Apollo Rover CLI: https://go.apollo.dev/t/migration
-----------------------------------------------------------------
See code: src/commands/service/delete.ts
apollo service:download OUTPUT
[DEPRECATED] Download the schema from your GraphQL endpoint.
USAGE
$ apollo service:download OUTPUT
ARGUMENTS
OUTPUT [default: schema.json] Path to write the introspection result
to. Supports .json output only.
OPTIONS
-c, --config=config Path to your Apollo config file
-g, --graph=graph The ID of the graph in the Apollo registry for
which to download the schema for. Overrides
config file if provided.
-k, --skipSSLValidation Allow connections to an SSL site without certs
-v, --variant=variant The variant to download the schema of
--endpoint=endpoint The URL for the CLI use to introspect your
service
--header=header Additional header to send during introspection.
May be used multiple times to add multiple
headers. NOTE: The `--endpoint` flag is
REQUIRED if using the `--header` flag.
--key=key The API key to use for authentication to Apollo
DESCRIPTION
-----------------------------------------------------------------
DEPRECATED: This command will be removed from the `ng-apollo` CLI in
its next major version. Replacement functionality is available in
the new Apollo Rover CLI: https://go.apollo.dev/t/migration
-----------------------------------------------------------------
ALIASES
$ apollo schema:download
See code: src/commands/service/download.ts
apollo service:list
[DEPRECATED] List the services in a graph
USAGE
$ apollo service:list
OPTIONS
-c, --config=config Path to your Apollo config file
-g, --graph=graph The ID of the graph in the Apollo registry for
which to list implementing services. Overrides
config file if set.
-v, --variant=variant The variant to list implementing services for
--endpoint=endpoint The URL for the CLI use to introspect your
service
--header=header Additional header to send during introspection.
May be used multiple times to add multiple
headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--key=key The API key to use for authentication to Apollo
DESCRIPTION
-----------------------------------------------------------------
DEPRECATED: This command will be removed from the `ng-apollo` CLI in
its next major version. Replacement functionality is available in
the new Apollo Rover CLI: https://go.apollo.dev/t/migration
-----------------------------------------------------------------
See code: src/commands/service/list.ts
apollo service:push
[DEPRECATED] Push a service definition to Apollo
USAGE
$ apollo service:push
OPTIONS
-c, --config=config
Path to your Apollo config file
-g, --graph=graph
The ID of the graph in Apollo to publish your service to. Overrides
config file if set.
-v, --variant=variant
The variant to publish your service to in Apollo
--author=author
The author to associate with this publication
--branch=branch
The branch name to associate with this publication
--commitId=commitId
The SHA-1 hash of the commit to associate with this publication
--endpoint=endpoint
The URL for the CLI use to introspect your service
--header=header
Additional header to send during introspection. May be used multiple
times to add multiple headers. NOTE: The `--endpoint` flag is REQUIRED
if using the `--header` flag.
--key=key
The API key to use for authentication to Apollo
--localSchemaFile=localSchemaFile
Path to one or more local GraphQL schema file(s), as introspection
result or SDL. Supports comma-separated list of paths (ex.
`--localSchemaFile=schema.graphql,extensions.graphql`)
--serviceName=serviceName
Provides the name of the implementing service for a federated graph
--serviceRevision=serviceRevision
Provides a unique revision identifier for a change to an implementing
service on a federated service push. The default of this is a git sha
--serviceURL=serviceURL
Provides the url to the location of the implementing service for a
federated graph
DESCRIPTION
-----------------------------------------------------------------
DEPRECATED: This command will be removed from the `ng-apollo` CLI in
its next major version. Replacement functionality is available in
the new Apollo Rover CLI: https://go.apollo.dev/t/migration
-----------------------------------------------------------------
ALIASES
$ apollo schema:publish
See code: src/commands/service/push.ts
Configuration
The Apollo CLI and VS Code extension can be configured with an Apollo config file. Apollo configuration is stored as a plain object in an apollo.config.js
file which exports the configuration. For more information about configuring an Apollo project, see: https://www.apollographql.com/docs/devtools/apollo-config/.
Note: the use of the
apollo
key in the project's package.json file for configuration is deprecated, and will no longer be supported in Apollo v3
You'll need to set up your Apollo configuration for all the features of the Apollo CLI and VS Code extension to work correctly. For full details on how to do that, visit our docs. A basic configuration (apollo.config.js
style) looks something like this:
module.exports = {
client: {
name: "My Client Project",
service: "my-service-name"
}
};
Code Generation
Accompanying Libraries
See Apollo iOS for details on the mapping from GraphQL results to Swift types, as well as runtime support for executing queries and mutations. For Scala, see React Apollo Scala.js for details on how to use generated Scala code in a Scala.js app with Apollo Client.
gql
template support
If the source file for generation is a JavaScript or TypeScript file, the codegen will try to extrapolate the queries inside the gql tag templates.
The tag name is configurable using the CLI --tagName
option.
Typescript and Flow
When using the codegen command with Typescript or Flow, make sure to add the __typename
introspection field to every selection set within your graphql operations.
If you're using a client like apollo-client
that does this automatically for your GraphQL operations, pass in the --addTypename
option to apollo codegen:generate
to make sure the generated Typescript and Flow types have the __typename
field as well. This is required to ensure proper type generation support for GraphQLUnionType
and GraphQLInterfaceType
fields.
Why is the __typename field required?
Using the type information from the GraphQL schema, we can infer the possible types for fields. However, in the case of a GraphQLUnionType
or GraphQLInterfaceType
, there are multiple types that are possible for that field. This is best modeled using a disjoint union with the __typename
as the discriminant.
For example, given a schema:
...
interface Character {
name: String!
}
type Human implements Character {
homePlanet: String
}
type Droid implements Character {
primaryFunction: String
}
...
Whenever a field of type Character
is encountered, it could be either a Human or Droid. Human and Droid objects
will have a different set of fields. Within your application code, when interacting with a Character
you'll want to make sure to handle both of these cases.
Given this query:
query Characters {
characters(episode: NEW_HOPE) {
name
... on Human {
homePlanet
}
... on Droid {
primaryFunction
}
}
}
Apollo Codegen will generate a union type for Character.
export type CharactersQuery = {
characters: Array<
| {
__typename: "Human",
name: string,
homePlanet: ?string
}
| {
__typename: "Droid",
name: string,
primaryFunction: ?string
}
>
};
This type can then be used as follows to ensure that all possible types are handled:
function CharacterFigures({ characters }: CharactersQuery) {
return characters.map(character => {
switch (character.__typename) {
case "Human":
return (
<HumanFigure
homePlanet={character.homePlanet}
name={character.name}
/>
);
case "Droid":
return (
<DroidFigure
primaryFunction={character.primaryFunction}
name={character.name}
/>
);
}
});
}
Contributing
This repo is composed of multiple packages. The apollo-cli
contains the core CLI commands. The apollo-codegen-core
package contains all the compiler APIs needed to implement code generation support for new languages. The other apollo-codegen-*
packages implement code generation support for individual languages.
Running tests locally:
npm install
npm test
You can also run npm
commands within package folders after you have bootstrapped the repository (part of npm install
).
Note: if you have issues, try
npm run clean && npm i
to get a fresh install of the packages. Occasionally problems arise when removed dependencies stay around
Nock tests
To display the debugging messages for nock, run the following command:
DEBUG=nock.* npm test
It can also be helpful to print standard out during testing. To enable logging, add the following configuration to the stdout
function call during test creation:
.stdout({ print: true })
Active Development / Debugging
To simplify the development process, you may want to step through and debug commands whose behavior you're modifying. To do this, run the executable with node in debug mode like so, where <command>
is a valid CLI command like client:check
or service:push
:
node --inspect-brk=9002 packages/apollo/bin/run <command>
If you're using VS Code, you can run the included "Attach to CLI Debugger" launch task and debug right from VS Code! Otherwise, you may use the Chrome inspector or other Node debugger of your choice.
Regenerating Mocked Network Data
Some integration tests rely on mocked server data (service:check for example). Mock data is generated by making real network requests and recording those requests with nock
's recording feature. Stop mocking network calls and add nock.recorder.rec()
before network calls are made. For service:check
, change apiKey
to a real Apollo API key. Then run the tests and nock will output code to mock requests to the console. You can (and probably should) pare down the request to be less brittle (by only checking for an operation name, for example). See src/commands/service/__tests__/check.test.ts
for an example of how a mocked network request will look.
Publishing
- Make sure the
CHANGELOG.md
is updated with all changes committed since the last release. Make sure the versions for each package to update are correct. - Run
npm run release:version-bump -- <bumpish>
- Can use major, minor, patch, prepatch, etc for the bump type. If not used, the command will prompt and ask for the bump type.
- This command updates git tags locally and on GitHub
- Run npm run release:start-ci-publish locally
- IMPORTANT: If publishing a prerelease (like
alpha
/beta
/rc
), set the tag that NPM will use to publish with theAPOLLO_DIST_TAG
environment variable. By default, if this isn't set, NPM will publish the prerelease to thelatest
tag (which isn't what we'd want). - Pushes a
publish/XXXXXXXXXX
tag to GitHub to trigger circle CI build
- IMPORTANT: If publishing a prerelease (like
- Circle will notify the appropriate Apollo team slack channel when ready to release
- Slack channel member will confirm through the Apollo Deploy Bot
- Circle will release to all channels (npm, cli binary to s3, vscode marketplace)
- Another slack bot notification will confirm success of release.
Maintainers
- @JakeDawkins (Apollo)