nself api

Inspect the live nSelf GraphQL API version, check deprecation status of fields and operations, and verify your client apps are on supported surfaces.

Quick start

# Print the live API version and LTS window
nself api version

# Scan your GraphQL operations for deprecated fields
nself api deprecation-check

Synopsis

nself api <SUBCOMMAND> [FLAGS]

Description

nself api provides tooling for operators who care about GraphQL API stability across upgrades. It surfaces two things: the version metadata of the running Hasura API (including which LTS window it falls in), and a deprecation scanner that reads your project's.graphql operation files and checks them against the live schema's @deprecated directives.

Running nself api deprecation-check as part of your CI pipeline catches usage of deprecated fields before they are removed in the next minor release. This is especially useful for teams that generate typed clients from the schema (via nself generate).

The --surface flag on api version lets you query a specific API surface (Hasura, Auth, or ping_api) instead of the default Hasura GraphQL endpoint.

Subcommands

nself api version

Query the live API and print version, surface, Hasura build info, and LTS window.

nself api version
# Surface:    hasura
# Version:    v2.36.1
# CLI:        v1.1.0
# LTS window: 2025-11-01 → 2026-11-01
# Status:     supported

nself api version --surface auth
nself api version --json

nself api deprecation-check

Scan all .graphql files in the project for operations that use fields or types marked @deprecated in the live schema. Prints a report of affected operations and the removal target version.

nself api deprecation-check
# OPERATION                  FILE                    DEPRECATED FIELD      REMOVAL
# GetUserProfile              queries/user.graphql    user.legacyId         v1.2.0
# ListProjects                queries/projects.graphql project.archivedAt   v1.2.0

nself api deprecation-check --json
nself api deprecation-check --dir ./src/graphql

Examples

Check API version in CI

nself api version --json | jq '.status'
# "supported"

Fail the build if deprecated fields are in use

nself api deprecation-check --fail-on-deprecated
# exits 1 if any deprecated field found in .graphql files

Check auth surface version

nself api version --surface auth --json | jq '{version, lts_end}'

Scan a specific directory

nself api deprecation-check --dir ./apps/web/src/graphql --json

Environment variables

• NSELF_HASURA_ENDPOINT — Hasura GraphQL endpoint (default: from project .env)
• NSELF_HASURA_ADMIN_SECRET — Hasura admin secret for schema introspection

Exit codes

• 0 — success (or no deprecated usage found)
• 1 — API unreachable, or deprecated usage found when --fail-on-deprecated is set
• 2 — invalid arguments

Related

• nself generate — generate typed SDK clients from the live schema
• nself health — service-level health checks
• nself version — CLI version and build info