Command reference

This page lists every command the gpilot CLI provides. Append --help to any command for its complete, authoritative set of flags. All commands also accept the global options (--profile, --format, --no-interactive, --no-color, --quiet).

Tip

Most resource commands operate on a currently selected organization and service. Use organization select and service select to choose them once, or pass an override flag (such as --service) per command.

Shortcuts

A few common actions have top-level shortcuts. Each one is also shown on the subcommand it expands to, below.

Command	Expands to
gpilot login	gpilot auth login
gpilot logout	gpilot auth logout
gpilot whoami	gpilot auth status
gpilot deploy	gpilot deployment create
gpilot status	gpilot deployment list
gpilot cancel	gpilot deployment cancel
gpilot requests	gpilot service requests
gpilot purge	gpilot service purge

Command groups and subcommands have aliases, listed with each one below. gpilot pq is gpilot persisted-query, and pq ls is the same command as pq list. The rest of the documentation writes the subcommands by their names (gpilot pq list, gpilot pq push, gpilot pq rm, gpilot apq ls, gpilot apq rm).

Not in the CLI

Deleting an organization is done in the portal only. Deleting a service is different: gpilot service delete deletes it, with the emailed code. There is no gpilot settings command either (the CLI refuses it as an unknown command, with exit 2): the CLI’s own settings are its environment variables and profiles. A schema reaches GraphPilot with gpilot deploy; gpilot schema pull only reads one.

gpilot auth

Log in, log out, and inspect the current session. Managing the profiles those credentials live in is gpilot profile. See Signing in and Profiles for the full workflow.

login

shortcut

gpilot login

gpilot auth login

Log in via browser, device code, or API key.

Argument	Description
--browser	Log in via browser (OAuth2 authorization code flow).
--device	Log in via device code, for headless or CI environments.
--api-key [KEY]	Log in with an organization API key. Omit KEY to be prompted securely.
--org <slug>	Skip the organization picker and use this slug directly. With --api-key, the login is refused when the key belongs to a different organization.
-f, --force	Force re-authentication even if already logged in.

--browser, --device and --api-key exclude each other. Without any of them the command asks which method to use; in non-interactive mode it refuses and exits 1.

The global --profile <name> option chooses which profile to log into; it is created if it does not exist: gpilot --profile acme auth login. A successful login makes the profile active.

logout

shortcut

gpilot logout

gpilot auth logout

Remove the stored credential for the active profile, leaving the profile itself (and its selected service) in place. To remove a profile entirely, use profile delete.

Argument	Description
--all	Log out of every profile. Cannot be combined with --profile.

status

shortcut

gpilot whoami

gpilot auth status

Show the current authentication status, verifying validity against the API.

Argument	Description
--offline	Skip the online validity check and report the stored state only.

With -o json or -o yaml it prints one document; its fields are listed under check your status.

Pass the global --profile <name> to inspect a profile other than the active one: gpilot --profile acme auth status.

gpilot profile

Aliases: p, prof. Manage the named slots the CLI stores credentials in. Every subcommand here reads and writes local state only and never calls the GraphPilot API. See Profiles.

list

gpilot profile list

List configured profiles: the active one (marked *), its organization, authentication method, and the email behind an OAuth login.

No arguments.

show

gpilot profile show [name]

Show a profile’s stored context: organization, selected service, email, remaining token lifetime, and an api_url override when one is set. The offline counterpart to auth status. Its -o json document is shown under inspect one profile.

Argument	Description
[name]	Profile to show. Defaults to the active profile.

use

gpilot profile use <name>

Switch the active profile.

Argument	Description
<name>	Profile to make active.

rename

gpilot profile rename <old> <new>

Rename a profile, credential and configuration together, without logging in again. Refused if <new> already exists.

Argument	Description
<old>	Profile to rename.
<new>	New name.

delete

gpilot profile delete <name>...

Remove profiles whole: the credential and the config.toml entry. Every name is validated before anything is deleted. Deleting the active profile falls back to default.

Argument	Description
<name>...	Profiles to delete. Required unless --all is given.
--all	Delete every configured profile.
-y, --yes	Skip the confirmation prompt. Required in non-interactive shells.

gpilot organization

Aliases: o, org. Manage organizations and choose the one the CLI works in.

Organizations are deleted in the portal, which asks for a confirmation code sent to you by email. Deleting an organization is not available from the CLI.

list

gpilot organization list

List all organizations you can access. Alias: ls.

No arguments.

show

gpilot organization show <slug>

Show a single organization.

Argument	Description
<slug>	Organization slug.

create

gpilot organization create --name "Your Company" --accept-terms

Create a new organization. Alias: new.

Argument	Description
-n, --name <name>	Organization name (required).
-s, --slug <slug>	Slug; auto-generated from the name if omitted.
-w, --website-url <url>	Website URL.
-i, --industry <industry>	Industry.
--accept-terms	Accept the GraphPilot terms in force. Required, see below.

Creating an organization accepts the GraphPilot terms in force. The command reads the current version from the API (legalTerms) and accepts exactly that version, and only when you pass --accept-terms. Without the flag it creates nothing, prints the version, the URL of the terms and the URL of the privacy policy (linked for information, it is not accepted), and exits 1. In an interactive terminal it asks instead, and the answer defaults to no. In non-interactive mode, as in CI, the flag is the only way to accept; --yes does not accept the terms.

If the terms change between the moment the command reads them and the moment it creates the organization, the API refuses with TERMS_NOT_ACCEPTED and nothing is created. The command names the version now in force and exits 1; run it again with --accept-terms to accept that version.

Note

Not available for API-key sessions: creating an organization is a user-level action that needs an interactive user login (--browser or --device).

edit

gpilot organization edit <slug>

Edit an organization.

Argument	Description
<slug>	Organization to edit.
--name <name>	New name.
--new-slug <slug>	New slug.
--website-url <url>	New website URL.
--industry <industry>	New industry.

select

gpilot organization select [slug]

Set the active organization. Alias: use.

Argument	Description
[slug]	Organization slug. Interactive selection if not provided.

Note

For API-key sessions the organization is fixed by the key, so organization select will not switch it. For browser/device sessions, selecting re-mints an organization-scoped token.

gpilot service

Aliases: s, svc. Manage the services in the active organization.

Services are deleted with service delete or in the portal; both ask for a confirmation code sent to you by email. To take a service off the edge but keep it, use service destroy.

list

gpilot service list

List services in the active organization. Alias: ls.

No arguments.

show

gpilot service show <subdomain>

Show a single service: its name, subdomain, URL, origin URL and environment.

Argument	Description
<subdomain>	Service subdomain.

URL is the service’s primary address: its custom domain when one is primary, otherwise https://<subdomain>.<label>.graphpilot.cloud under your organization’s hostname label (https://<subdomain>.graphpilot.cloud for a service created before labels). gpilot service list prints the same column. Other custom domains and the service ID are shown in the portal, not by this command.

create

gpilot service create

Create a new service. Alias: new.

Argument	Description
-n, --name <name>	Service name (required).
-s, --subdomain <subdomain>	Subdomain, unique within the organization; auto-generated from the name if omitted. The service answers on <subdomain>.<label>.graphpilot.cloud, which service create prints as URL.
-u, --url <url>	Origin URL (required). Scheme, host and optional port only; a URL with a path, query or fragment is refused. Without a port, https:// connects to 443 and http:// to 80.
-e, --environment <env>	Environment, e.g. production or staging. Defaults to production.
--color <hex>	Display color as a hex code, e.g. #FF5733. Defaults to #3B82F6.

| --deploy | Deploy right away without asking: no schema, the default configuration, then GraphQL detection through the service’s hostname. Conflicts with --no-deploy. | | --no-deploy | Only create the service. | | --keep-plain-http | Never apply a detected schema and configuration: finish the setup with the service as plain HTTP. | | --detach | Start the first deployment and return without following the setup. | | --timeout <duration> | Maximum time to follow the setup, such as 30m or 1h. Defaults to 30m. Time spent answering a question does not count. Nothing is canceled when it runs out. | | -y, --yes | Answer every question with its default: deploy, apply the detected schema and configuration, and keep probing an origin the edge cannot reach, every 30 seconds, until --timeout. |

--name and --url are required; the command does not prompt for them.

The command prints the service’s signing key once, as the Signing key row (signing_key with -o json or -o yaml), and says so on stderr. GraphPilot never shows it again, so store it right away; if you lose it, rotate it in the portal. See the signing key. In the default format the table with the key is printed as soon as the service exists, before the setup starts.

Deploying right away

service create runs the same setup as the portal: a first deployment without a schema and without a configuration file, then GraphQL detection, then, if GraphQL was found, a second deployment with the detected schema and configuration.

1. Whether to deploy. --no-deploy creates the service only. Without a terminal and without --deploy or --yes, it also creates only, as before. Otherwise the CLI first asks GraphPilot whether the edge can reach the origin URL; a private or local address is not deployed, and the CLI prints Your origin is on a private address that the edge cannot reach. Deploy once it is reachable from the internet. and creates only. With --deploy or --yes it deploys; otherwise it asks Deploy right away? (no schema, default configuration; GraphPilot then looks for GraphQL on your origin), default yes.
2. Following the setup. With --detach it prints Deploying. Follow the setup with: gpilot service setup --service <subdomain> and exits. Otherwise it prints GraphPilot’s sentence for each state of the setup, once, on stderr, and then:
   • GraphQL found, with a schema: a table of the probed paths (Path, Status, Result), GraphQL answers on <path>; introspection read a schema with <n> types., and, when the suggestion sets a path, The suggested configuration sets request.graphql_paths to ["<path>"]. It asks Apply the suggested configuration and schema? This deploys the service again, with its GraphQL features on, default yes. No, or --keep-plain-http, keeps the service as plain HTTP.
   • GraphQL found without a schema, or no GraphQL: the findings, with No GraphQL endpoint was detected, so the service runs as plain HTTP. If your API answers GraphQL on another path, set request.graphql_paths in gpilot.toml and deploy with: gpilot deploy when nothing answered. When introspection failed, it suggests gpilot schema pull with the credentials your API needs. It asks Keep the service as plain HTTP?, default yes; no leaves the setup open.
   • The edge could not reach the origin: the edge’s IPv4 and IPv6 ranges to allow at your firewall. It asks Retry detection?, default yes; with --yes it probes again every 30 seconds.
   • Without a terminal and without --yes, a question is left open rather than answered: the CLI prints The setup of service '<subdomain>' is waiting for your decision. with the gpilot service setup command that continues it, and exits 0.
3. At the end it prints a summary: Setup done. with the outcome (The service serves GraphQL with the detected schema, The service runs as plain HTTP or A deployment of your own replaced the automatic one), or the state the setup is in, and the rows Service, URL, Setup, GraphQL path, Schema types and Deployment.

With -o json, -o yaml or -o jsonl it prints one document at the end, also when the setup failed, so the signing key is never lost: the service’s name, subdomain, url, origin_url, environment and signing_key, and setup (null without one), with service, url, state, outcome, message, errorCode, graphqlPath, typeCount, initialDeploymentId and appliedDeploymentId in the API’s words (DONE, GRAPHQL). Progress and questions go to stderr.

Exit code	When
0	Created, set up, skipped for a private origin, detached, or a question was left open.
1	The setup failed (The setup of service '<subdomain>' failed: <message>), the origin stayed unreachable and no retry was taken, or --timeout ran out (... is still <STATE> after --timeout ran out. Nothing was cancelled). Each names the command to continue with.
130, 143	You stopped following the setup with Ctrl+C (130) or SIGTERM (143, Unix). The command prints its normal output first (with -o, the one document, signing key included) and says Stopped following the setup of service '<subdomain>'; it goes on at GraphPilot with the gpilot service setup command to follow it. The setup is not canceled.
2	A usage error, such as --deploy with --no-deploy.
3	Authentication failed.
4	A network or API failure.

setup

gpilot service setup

Follow or resume the setup of a service: the same steps, questions, output and exit codes as service create from the moment the service exists, except 130 and 143, which only service create returns. At the end it prints the summary, or with -o a document of the setup alone.

Argument	Description
--service <subdomain>	Override the active service.
--retry	Probe the origin again first. Also starts a setup for a service created without deploying, once one of its deployments has completed.
--keep-plain-http	Never apply a detected schema and configuration.
-y, --yes	Answer every question with its default.
--timeout <duration>	Maximum time to follow the setup. Defaults to 30m. Time spent answering a question does not count.

A service without a setup is refused with Service '<subdomain>' has no setup to follow: it was created without deploying and exit 1; start one with --retry.

edit

gpilot service edit <subdomain>

Edit a service.

Argument	Description
<subdomain>	Service subdomain to update.
--name <name>	New name.
--new-subdomain <subdomain>	New subdomain.
--url <url>	New origin URL.
--environment <env>	New environment.
--color <hex>	New color (hex code).

select

gpilot service select [subdomain]

Set the active service. Alias: use.

Argument	Description
[subdomain]	Service subdomain. Interactive selection if not provided.

delete

gpilot service delete <subdomain>

Delete a service and tear down its edge infrastructure. Alias: rm. Its deployments, schema and configuration go with it, and this cannot be undone. To take a service off the edge but keep it, use service destroy instead.

Argument	Description
<subdomain>	Service subdomain to delete.
--code <code>	The confirmation code GraphPilot emailed for this deletion. Skips requesting a new code and the confirmation prompt.
-y, --yes	Skip the confirmation prompt before the code is requested.

GraphPilot confirms a deletion with a code it emails to the person asking. Without --code, the command says what is about to be deleted, asks you to confirm, has GraphPilot email you a code and asks for it. Once the code is accepted, the service is deleted and the command exits 0; its edge infrastructure is torn down in the background.

• It needs a user login. With an API key (an API-key profile or GPILOT_TOKEN) the command refuses before sending anything and exits 1, because a key has no inbox. Sign in with gpilot auth login, or delete the service in the portal.
• Without a terminal to ask on, it refuses without --yes and exits 1. With --yes it requests the code, has nowhere to type it in, and exits 1 without deleting; finish with gpilot service delete <subdomain> --code <code>.
• A code that is not accepted (mistyped, expired or already used) exits 1 and deletes nothing. Run again with --code for a typo, or without it for a new code.

destroy

gpilot service destroy <subdomain>

Tear down the deployed infrastructure of a service while keeping the service itself, its schema, its config and its history. Deploy again to bring it back.

Argument	Description
<subdomain>	Service whose deployed infrastructure should be torn down.
-y, --yes	Skip the confirmation prompt. Required in non-interactive runs, where the command otherwise refuses and exits 1.

The teardown runs in the background, so the command reports that the request was accepted rather than waiting for it.

runtime

gpilot service runtime show
gpilot service runtime pin <version>
gpilot service runtime unpin

Show or change the proxy runtime version a service runs. See Runtime versions.

Subcommand	Description
show	Shows the version the service runs now, whether it follows stable or is pinned, and the version its next deployment gets. For a service pinned to a withdrawn version, whose deployments are refused, that last row reads Unknown (no runtime version resolvable).
pin <version>	Keeps the service on one version. A withdrawn or unknown version is refused.
unpin	Lets the service follow the stable version again.

All three take --service <subdomain> to override the active service.

pin and unpin redeploy the service, so they need service:edit and deployment:edit.

requests

shortcut

gpilot requests

gpilot service requests [filters] [--follow | --wait[=N]]

Inspect and tail request telemetry. Alias: req. Without flags it prints the last 50 matching requests from the past 15 minutes.

It reads stored request telemetry, so it shows only requests that were stored; see what Insights needs. The filters need the same plan as their Insights counterparts; a filter your plan does not include is refused.

Argument	Description
--path <glob>	Filter by request path. Wildcards supported, repeatable, ORed.
--operation <name>	Filter by GraphQL operation name. Wildcards supported, repeatable, ORed.
--method <method>	Filter by HTTP method. Repeatable, ORed.
--status <code>	Filter by HTTP response status. Repeatable, ORed.
--correlation-id <id>	Filter by correlation id, the value the client sent in GP-Correlation-ID (see telemetry.correlation_header). Exact match, repeatable, ORed. Needs Airliner (Business) or above; on a smaller plan the API refuses the request with FORBIDDEN and the command exits 4.
--request-id <id>	Filter by request id, the value of the gp-request-id response header. Exact match, repeatable, ORed. Needs Airliner (Business) or above; on a smaller plan the API refuses the request with FORBIDDEN and the command exits 4.
--surrogate-key <key>	Filter to responses that carried this surrogate key. Exact match, repeatable, ORed. Needs Airliner (Business) or above, like --request-id.
--wide	Add the request id, the cache reason (pass reason, else skip reason), the cache key and the surrogate keys to the table.
--ip[=<ip>]	Filter by client IP. Bare --ip uses your public IP as GraphPilot’s API sees it (Query.clientIp), looked up once at start; no third-party service is asked. When the API knows no address for your connection, the command fails with Pass it explicitly with --ip=<address>. rather than listing unfiltered rows. The match is exact: on a service whose telemetry.client_ip is "truncated", pass the truncated address; with "none", nothing matches.
--since <dur>	How far back to look. Default 15m.
--limit <n>	Maximum rows per query. Default 50.
-f, --follow	Tail new matching requests as they arrive. How long it runs is below the table.
--wait[=N]	Wait until N matching requests exist, then print and exit. Default N=1.
--timeout <dur>	Maximum time to wait in --wait mode. Default 120s.
--poll-interval <dur>	Poll interval for --wait. Default 3s. Ignored by --follow, which the server paces.
--service <subdomain>	Override the active service.

--wait is what you want in a test or a CI step: it blocks until the request you are expecting shows up rather than racing it.

The server closes a live stream after five minutes without a new matching request. --follow reconnects on its own when that happens, picking up after the last row it printed without repeating one, so it runs until you stop it with Ctrl+C. It stops earlier, with an error, when the server answers with an error (a credential that stopped working, for example), the connection closes, or reconnecting fails.

The table shows time, status, method, latency, cache status, path and correlation ID, then the GraphQL operation name (OPERATION) as the last column, never cut short; --wide adds REQUEST ID, REASON, CACHE KEY and SURROGATE KEYS before it. On a narrow terminal the correlation ID, cache status, method and path columns are dropped, in that order, until the line fits; --wide drops nothing. With -o json, -o jsonl or -o yaml, each row carries id, timestamp, correlation_id, method, path, status, cache_status, operation, latency_ms, cache_key, pass_reason, skip_reason and surrogate_keys. A field your plan does not list comes back empty (null): the cache key and the surrogate keys are listed from Airliner (Business); the cache status and the reasons are listed on every plan. --follow streams only as the table or as -o jsonl; json and yaml produce a single document and cannot tail.

To find one request, filter by its request id (--request-id) or its correlation ID. Purge events are not part of this output; the portal shows them.

purge

shortcut

gpilot purge

gpilot service purge [<key>...] [--all] [--soft]

Purge cached responses. See invalidation for what a key is and which one to reach for.

Argument	Description
[<key>...]	Surrogate keys to purge. Reads from stdin, one key per line, when none are given and stdin is not a terminal.
--all	Purge the service’s entire cache.
--soft	Mark entries stale instead of evicting them, so a revalidation serves rather than a miss. Conflicts with --all.
--service <subdomain>	Override the active service.
-y, --yes	Skip the confirmation prompt. Required in non-interactive runs, where the command otherwise refuses and exits 1.

Every purge asks for confirmation, naming the service and its environment. Reading keys from stdin lets you purge a list produced by another tool:

sort -u keys.txt | gpilot purge --yes

With -o json (or yaml) it prints the API’s own purge payload, field names included:

{
  "success": true,
  "purgedKeyCount": 2,
  "purgedKeys": ["User:id:1", "User:id:2"]
}

purgedKeyCount counts keys, not cached responses. A purge-all reports 0 and an empty list.

gpilot runtime

Look up the proxy runtime versions. Neither command needs a login. To see or change what a service runs, use service runtime.

versions

gpilot runtime versions

List the runtime versions, newest first, with the stable one marked. Alias: ls.

Argument	Description
--include-yanked	Also list withdrawn versions, with the reason they were withdrawn.

changelog

gpilot runtime changelog --from <version> [--to <version>]

Print what changed in the runtime after a version.

Argument	Description
--from <version>	The version you run now; the changelog starts after it (required).
--to <version>	The last version to include. Defaults to the current stable version.

gpilot deployment

Aliases: d, dpl. Create and manage deployments for the active service.

create

shortcut

gpilot deploy

gpilot deployment create

Create a new deployment. Alias: new.

Argument	Description
-s, --schema <file>	Path to the GraphQL schema file. Optional; defaults to schema.graphql or schema.gql in the current directory. When neither exists, the service is deployed without a schema, as a plain HTTP service with GraphQL features off. A path given here that does not exist is an error.
-c, --config <file>	Path to the service config: TOML, JSON, JSON5 or YAML, picked by extension. Anything that is not TOML is converted before it is uploaded. Optional; defaults to the first of gpilot.toml, gpilot.tml, gpilot.json, gpilot.json5, gpilot.yaml and gpilot.yml in the current directory. A [runtime] version in it applies to this deployment only.
--detach	Create the deployment and return immediately, without waiting for it to finish. Alias: --no-wait.
--timeout <duration>	Maximum time to wait for the deployment when not using --detach, watching its progress and, if the stream ends early, checking it until it ends. Accepts human durations such as 20m, 1h 30m, or 900s. Defaults to 20m.
--no-schema	Deploy as a plain HTTP service even when schema.graphql or schema.gql is present. Conflicts with --schema. Prints the No schema found line below.
--default-config	Deploy on GraphPilot’s default configuration: no config file is read or uploaded, and no [runtime] version applies. The summary shows Config: GraphPilot defaults, no config file. Conflicts with --config.
--force-build	Force a rebuild even if nothing changed.
--service <subdomain>	Override the active service.
-y, --yes	Skip the confirmation prompt.

By default gpilot deploy waits for the deployment to finish, streaming per-step progress (build, edge deploy, TLS verification, activation) as it runs, and exits non-zero if the deployment fails or the wait exceeds --timeout. If the progress stream ends before the deployment does, it keeps checking the deployment within the same --timeout, and exits 7 only if the deployment is still open when that runs out. Pass --detach to create the deployment and return immediately, leaving it to run in the background.

In a non-interactive context the confirmation prompt is skipped automatically, so deploys run unattended in CI without --yes (see interactive vs. non-interactive).

When --schema or --config are omitted, the CLI looks for the conventional file names in the current directory (the first match wins). This lets you run gpilot deploy with no arguments from a project that follows the standard layout. If no config file is found, the command exits with an error naming the candidates it looked for; pass --default-config to deploy without one. A deployment without a config file is printed with Config: default configuration in place of its config version.

A schema is optional. Without --schema and without a schema.graphql or schema.gql, the command deploys the configuration alone, as a plain HTTP service, and says so before it asks you to continue:

No schema found: deploying as a plain HTTP service, GraphQL features are off.

Nothing is uploaded for the schema, and the schema the service had before is not reused. When the live deployment had a schema, the summary of what changed shows Schema removed: GraphQL features off. The next deployment with a schema turns GraphQL on again. When the build completes, its diagnostics include a notice that the service has no schema; notices are printed as notices, not as errors, and never fail the command.

With -o json, -o jsonl or -o yaml, gpilot deploy prints one document as soon as the deployment exists: id, status (lowercase, as in gpilot status -o json), created_at, schema_version and config_version. Progress goes to stderr, and the outcome is the exit code; read the result afterwards with gpilot status -o json (below).

list

shortcut

gpilot status

gpilot deployment list

List deployments for the active service. Alias: ls.

Argument	Description
--service <subdomain>	Override the active service.

With -o json, -o jsonl or -o yaml, each deployment carries id, status, created_by (who requested it: a person by email, an API key by its name and redacted value such as CI (sk_...9W8H), or empty when nothing was recorded), created_at and completed_at (empty while it runs). status is one of started, pending, completed, failed or cancelled, and unknown for a status this CLI version does not know.

gpilot status -o json | jq -r '.[0].status'

cancel

shortcut

gpilot cancel

gpilot deployment cancel [id]

Cancel a deployment.

Argument	Description
[id]	Deployment ID. Interactive selection if not provided.
--service <subdomain>	Override the active service.
-y, --yes	Skip the confirmation prompt. Required in non-interactive runs, where the command otherwise refuses and exits 1.

gpilot persisted-query

Alias: pq. Manage the operations you declared for a service: the ones pushed from a manifest. What clients registered on their own through APQ is managed with gpilot apq. See Persisted queries for how they work and how to configure them.

list

gpilot persisted-query list [--search <text>] [--sort <name|hash>] [--documents] [--limit <n> | --all]

List the operations declared for a service (pushed from a manifest). Client registrations are not included; list those with apq ls. Alias: ls.

Argument	Description
--search <text>	Keep only operations whose name contains this text, case-insensitively. Matched literally: % and _ are ordinary characters. Anonymous operations have no name and never match.
--sort <name|hash>	Order the listing by operation name (A to Z, anonymous operations last) or by hash. Defaults to name.
--documents	Also print each entry’s GraphQL document.
--limit <n>	Stop after this many entries. Defaults to 50.
--all	List the whole manifest. Conflicts with --limit.
--service <subdomain>	Override the active service.

show

gpilot persisted-query show <hash>

Print one registered document, whether it was pushed or registered by a client.

Argument	Description
<hash>	SHA-256 of the document, hex encoded.
--service <subdomain>	Override the active service.

push

gpilot persisted-query push <path>... [--as <format>] [--rehash] [--dry-run]

Register operations from a manifest. Additive and idempotent: nothing is removed, and re-sending an entry is a no-op.

Argument	Description
<path>...	Manifests, .graphql sources, directories or globs. Repeatable. An argument is read as a glob only when no file or directory of that exact name exists, so an existing path such as src/app/[id]/q.graphql is read as it is, [, * and ? included.
--as <format>	Read the files as this format instead of detecting it from their contents: apollo, map, relay-array, operation-output or graphql-source. formats says which tool produces which.
--rehash	Register documents under GraphPilot’s hash even when the manifest declares a different id. Only correct when you are regenerating your clients too; on its own it registers documents under ids no client sends.
--dry-run	Parse, verify and report, but write nothing.
--service <subdomain>	Override the active service.

rm

gpilot persisted-query rm <hash>... | --from-file <file> | --all

Revoke operations: delete the registry entries and purge everything cached for them. Clients still sending these hashes will break, which is the intent. Alias: remove.

Argument	Description
<hash>...	Hashes to revoke, hex encoded.
--from-file <file>	Read hashes from a file, one per line.
--all	Revoke everything the registry holds.
--service <subdomain>	Override the active service.
-y, --yes	Skip the confirmation prompt. Required in non-interactive runs, where the command otherwise refuses and exits 1.

Exactly one of the three targets is required. To revoke only what clients registered, use apq rm --all.

formats

gpilot persisted-query formats

List the manifest formats push accepts, with the tools that produce each one and a link to their documentation.

No arguments.

gpilot apq

Manage what clients registered at the edge themselves through Automatic Persisted Queries (APQ), as opposed to the operations you pushed. See Persisted queries.

ls

gpilot apq ls [--limit <n> | --all]

List the hashes clients registered that your manifest does not declare. The listing shows hashes only; adopt an operation with pq push to give it a name. Alias: list.

Argument	Description
--limit <n>	Stop after this many entries. Defaults to 50.
--all	List every registration. Conflicts with --limit.
--service <subdomain>	Override the active service.

show

gpilot apq show <hash>

Print one registered document. The same command as persisted-query show.

Argument	Description
<hash>	SHA-256 of the document, hex encoded.
--service <subdomain>	Override the active service.

rm

gpilot apq rm <hash>... | --from-file <file> | --all

Revoke client registrations: delete the registry entries and purge everything cached for them. Clients still sending these hashes will break. To keep an operation, adopt it with pq push first and clear the rest afterwards. Alias: remove.

Argument	Description
<hash>...	Hashes to revoke, hex encoded.
--from-file <file>	Read hashes from a file, one per line.
--all	Revoke every client registration your manifest does not declare.
--service <subdomain>	Override the active service.
-y, --yes	Skip the confirmation prompt. Required in non-interactive runs, where the command otherwise refuses and exits 1.

Exactly one of the three targets is required.

gpilot schema

Read a GraphQL schema as SDL. It deploys nothing: a schema reaches GraphPilot with gpilot deploy.

pull

gpilot schema pull
gpilot schema pull --url https://api.example.com/graphql --header 'Authorization: Bearer ...' --output schema.graphql

Print the schema the active service is deployed from, or, with --url, the schema your API answers introspection with.

Argument	Description
--url <url>	Introspect this GraphQL endpoint instead. Conflicts with --service.
-H, --header <'Name: value'>	A header to send with the introspection query, such as a credential. Repeat for several. Requires --url.
--output <file>	Write the schema to this file instead of stdout, overwriting it without asking, and print Wrote the schema of <url or subdomain> to <file>. There is no default file name. --output, not -o, which is the global format option.
--timeout <duration>	How long to wait for the API to answer. Defaults to 30s. Requires --url.
--service <subdomain>	Override the active service.

Without --url it prints the schema of the service’s live deployment. A service without one is refused: Service '<subdomain>' is not deployed with a schema: it has no deployment yet, or it runs as plain HTTP.

With --url it asks your API directly from your machine, never through GraphPilot, with the standard introspection query and the headers you give, so an API that needs a credential for introspection still answers. The schema is printed in the usual SDL style, without built-in scalars, __ types and the specified directives. Deprecated fields, enum values, arguments and input fields are included, marked @deprecated. A server that cannot list deprecated arguments and input fields refuses that query; the CLI then asks again without them, warns <url> does not read deprecated arguments and input fields, so the schema was read without them: deprecated inputs may be missing, and the pull still succeeds. Introspection carries no applied directives: @cacheControl, @surrogateKey and @vary are absent, so add them to the file before you deploy it if you use them. Rules it applies:

• https:// only, except http:// without headers or to a loopback host (localhost, 127.x, [::1]): headers may carry a credential, so they are not sent over plain http:// to anything else.
• Redirects are not followed; the message names where it redirects, to pass with --url.
• An answer that is not JSON, or that carries no data, is refused with a message naming the status and the server’s own errors, and a hint to send a credential with --header or to allow introspection. Answers over 32 MiB are refused.
• An answer that carries any errors, even beside data, is refused as incomplete: <url> answered the introspection query with errors: <the server's messages>. So is one that leaves the members of a type empty (its fields, input fields, enum values or union members): The introspection answer does not list the members of type <type>, so the schema would be incomplete. Nothing was written.
• After any refusal nothing is written, and an existing --output file is kept as it was.
• Messages print the URL without credentials or query string.

Nothing but the schema goes to stdout. Exit 0 on success, 1 for every refusal above, 2 for a usage error, and 3 or 4 for an authentication or API failure (without --url only).

gpilot config

Aliases: c, cfg. Read and convert the service configuration, the gpilot.toml a deployment is built from. The CLI’s own settings on your machine are covered in environment variables and profiles.

get

gpilot config get [--to <format>] [--output <file>]

Print the config the service is currently deployed from. It comes back exactly as it was deployed, a JWT provider’s secret included, so this needs service:edit, for a member and an API key alike; with only service:view it is refused (FORBIDDEN). See permissions.

Argument	Description
--to <format>	Render as toml, json or yaml. Defaults to toml, which is the stored document and is printed byte for byte; the others are rendered from it.
--output <file>	Write to this file instead of stdout.
--service <subdomain>	Override the active service.

--to is not --format: the global --format decides how command output is rendered, which is a different question from what language this document is written in.

convert

gpilot config convert <path> [--to <format>] [--output <file>]

Convert a local config file between the accepted formats, without touching the deployed one.

Argument	Description
<path>	The file to convert. TOML, JSON, JSON5 or YAML, picked by extension.
--to <format>	Format to convert to. Defaults to toml, which is what a deploy uploads.
--output <file>	Write to this file instead of stdout.

gpilot completion

Generate shell completions. Supported shells: bash, zsh, fish, powershell, elvish.

gpilot completion <shell>

Argument	Description
<shell>	Shell to generate completions for.

Examples:

gpilot completion zsh > ~/.zfunc/_gpilot

gpilot completion bash > /usr/local/etc/bash_completion.d/gpilot