# client Command - Nitro > Reference for the `nitro client` commands: register GraphQL clients, upload versions with their persisted operations, and publish them to a stage. Canonical source: https://chillicream.com/docs/nitro/cli/client The `nitro client` commands manage clients of an API. A client is a registered consumer of a GraphQL API (for example a web app, a mobile app, or another service) along with the set of operations it sends. A client owns a sequence of versions, each identified by a tag and containing a set of persisted operations. Versions are published to a stage to mark them as live. All `client` commands require authentication. Run `nitro login` first or pass `--api-key` (see [Global Options](https://chillicream.com/docs/nitro/cli/global-options)). ## `nitro client create` Create a new client under an API. ``` nitro client create \ --name "" \ --api-id "" ``` ### Options | Option | Env | Description | | ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | \--name | NITRO\_CLIENT\_NAME | Display name of the client. Required. | | \--api-id | NITRO\_API\_ID | ID of the API the client belongs to. Required when no workspace is set in the session. Get the ID from nitro api list or the Nitro UI. | ### Examples Create a client interactively (prompts for missing values): ``` nitro client create ``` Create a client non-interactively: ``` nitro client create --name "" --api-id "" ``` ## `nitro client upload` Upload a new client version with the operations the client sends. The version is identified by a tag and is not yet published to any stage. ``` nitro client upload \ --client-id "" \ --tag "" \ --operations-file ``` ### Options | Option | Env | Description | | ------------------------------------ | ----------------------- | ------------------------------------------------------------------------ | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required. | | \--tag | NITRO\_TAG | Tag of the new client version, for example v1 or a Git commit. Required. | | \--operations-file | NITRO\_OPERATIONS\_FILE | Path to the JSON file with the persisted operations. Required. | ### Examples Upload a client version: ``` nitro client upload \ --client-id "" \ --tag "v1" \ --operations-file ./operations.json ``` ## `nitro client publish` Publish a previously uploaded client version to a stage. The version is identified by its tag. ``` nitro client publish \ --client-id "" \ --tag "" \ --stage "" ``` ### Options | Option | Env | Description | | ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required. | | \--tag | NITRO\_TAG | Tag of the client version to publish. Required. | | \--stage | NITRO\_STAGE | Name of the stage to publish to. Required. | | \--force | | Skip confirmation prompts and publish even when the version contains breaking operations. Mutually exclusive with \--wait-for-approval. | | \--wait-for-approval | NITRO\_WAIT\_FOR\_APPROVAL | Block the command until a reviewer approves the deployment. Mutually exclusive with \--force. Required when the stage gates deployments. | ### Examples Publish to `dev`: ``` nitro client publish \ --client-id "" \ --tag "v1" \ --stage "dev" ``` Publish to a gated stage and wait for approval: ``` nitro client publish \ --client-id "" \ --tag "v1" \ --stage "production" \ --wait-for-approval ``` ## `nitro client validate` Validate a new client version against a stage without publishing it. Run this in your pull request validation workflow to catch breaking operations before they are merged. ``` nitro client validate \ --client-id "" \ --stage "" \ --operations-file ``` ### Options | Option | Env | Description | | ------------------------------------ | ----------------------- | -------------------------------------------------------------- | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required. | | \--stage | NITRO\_STAGE | Name of the stage to validate against. Required. | | \--operations-file | NITRO\_OPERATIONS\_FILE | Path to the JSON file with the persisted operations. Required. | ### Examples Validate against the `dev` stage: ``` nitro client validate \ --client-id "" \ --stage "dev" \ --operations-file ./operations.json ``` ## `nitro client unpublish` Unpublish one or more client version tags from a stage. The version is not deleted, only removed from the stage. ``` nitro client unpublish \ --client-id "" \ --stage "" \ --tag "" ``` ### Options | Option | Env | Description | | ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------ | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required. | | \--stage | NITRO\_STAGE | Name of the stage to unpublish from. Required. | | \--tag | NITRO\_TAG | Tag of the client version to unpublish. Pass multiple times to unpublish several tags. Required. | ### Examples Unpublish a single tag: ``` nitro client unpublish \ --client-id "" \ --stage "dev" \ --tag "" ``` Unpublish multiple tags in one call: ``` nitro client unpublish \ --client-id "" \ --stage "dev" \ --tag "v1" \ --tag "v2" ``` ## `nitro client download` Download all persisted operations of the client currently published to a stage. Writes either a single JSON file (Relay-style) or a directory with one `.graphql` file per operation. ``` nitro client download \ --api-id "" \ --stage "" \ --path ``` ### Options | Option | Env | Description | | --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | \--api-id | NITRO\_API\_ID | ID of the API. Required. | | \--stage | NITRO\_STAGE | Name of the stage to download from. Required. | | \--path | | Path to write the operations to. A file path for relay, a directory for folder. Required. | | \--format | | Output format. relay writes a single JSON map of id -> operation, folder writes one file per operation. Defaults to relay. | ### Examples Download Relay-style persisted operations: ``` nitro client download \ --api-id "" \ --stage "dev" \ --path ./operations.json ``` Download as a folder of `.graphql` files: ``` nitro client download \ --api-id "" \ --stage "dev" \ --path ./operations \ --format folder ``` ## `nitro client list` List all clients of an API. Results are paginated, use the returned cursor to fetch the next page. ``` nitro client list --api-id "" ``` ### Options | Option | Env | Description | | ------------------ | -------------- | -------------------------------------------------------------------- | | \--api-id | NITRO\_API\_ID | ID of the API. Required when running non-interactively. | | \--cursor | NITRO\_CURSOR | Pagination cursor to resume from. Useful for non-interactive paging. | ## `nitro client list versions` List all versions of a client, including ones that have never been published to a stage. ``` nitro client list versions --client-id "" ``` ### Options | Option | Env | Description | | ------------------------ | ----------------- | -------------------------------------------------------------------- | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required when running non-interactively. | | \--cursor | NITRO\_CURSOR | Pagination cursor to resume from. Useful for non-interactive paging. | ## `nitro client list published-versions` List the versions of a client that are currently published to a given stage. ``` nitro client list published-versions \ --client-id "" \ --stage "dev" ``` ### Options | Option | Env | Description | | ------------------------ | ----------------- | -------------------------------------------------------------------- | | \--client-id | NITRO\_CLIENT\_ID | ID of the client. Required when running non-interactively. | | \--stage | NITRO\_STAGE | Name of the stage to list published versions for. Required. | | \--cursor | NITRO\_CURSOR | Pagination cursor to resume from. Useful for non-interactive paging. | ## `nitro client show` Show the details of a single client by its ID. ``` nitro client show "" ``` ### Arguments | Argument | Description | | -------- | ----------------------------------- | | | ID of the client to show. Required. | ## `nitro client delete` Delete a client by its ID. This removes the client and all of its versions. ``` nitro client delete "" ``` ### Arguments | Argument | Description | | -------- | ---------------------------------------------------------------------------------------------------------------- | | | ID of the client to delete. Required when running non-interactively. Interactive runs prompt to select a client. | ### Options | Option | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------- | | \--force | Skip the confirmation prompt. Required when running non-interactively (for example in CI) or together with \--output json. | [Edit this page on GitHub](https://github.com/ChilliCream/graphql-platform/edit/main/website/content/docs/nitro/cli/client.md) Last updated on **June 30, 2026** by **Tobias Tengler**