nself federation

Link multiple nSelf deployments via Hasura Remote Schema federation.

Quick start

# Link a remote nSelf project into this deployment
nself federation link https://api.your-other-project.com

# Check federation status
nself federation status

# Sync remote schema changes to the local Hasura instance
nself federation sync

Synopsis

nself federation link <PROJECT_URL> [FLAGS]
nself federation status [FLAGS]
nself federation sync [FLAGS]
nself federation unlink <PROJECT_URL> [FLAGS]

Description

nSelf Federation connects multiple independent nSelf deployments through Hasura Remote Schemas. Each linked project exposes its Hasura GraphQL endpoint as a remote schema in the local Hasura instance, making cross-project queries possible from a single GraphQL endpoint without merging databases.

Federation is one-directional: the local instance is the consumer (gateway), and the remote project is the provider. The remote project does not need to be modified — it only needs to be reachable and have its admin secret available.

Common use cases: connecting a shared auth backend, federating plugin data from a second nSelf install, or linking a staging instance to a shared analytics backend.

Remote schema definitions are stored in Hasura metadata. After any schema change on the remote project, run nself federation sync to reload the remote schema definition in the local instance.

Subcommands

nself federation link <PROJECT_URL>

Register a remote nSelf project as a Hasura Remote Schema. The CLI will prompt for the remote project's Hasura admin secret unless it is passed via --remote-secret.

nself federation link https://api.partner-project.com
# Prompts: Remote Hasura admin secret:
# Adding remote schema "partner-project"...
# Done. Reload Hasura console to see the federated schema.

nself federation status

Print the health of all linked remote schemas: reachability, last sync time, and any schema conflicts.

nself federation status
# REMOTE              URL                              STATUS   LAST SYNC
# partner-project     https://api.partner-project.com  healthy  2026-05-07 10:00

nself federation sync

Reload remote schema definitions from all linked projects. Run this after any schema change on a remote instance. Hasura will re-introspect each remote endpoint.

nself federation sync
# Syncing 2 remote schemas...
# partner-project: OK (14 new types, 0 conflicts)
# analytics-backend: OK (unchanged)

nself federation unlink <PROJECT_URL>

Remove a remote schema from this Hasura instance. Queries that referenced the remote schema will fail until the references are removed from your application.

nself federation unlink https://api.partner-project.com
# Removed remote schema "partner-project"

Flags

Examples

Link a shared auth backend

nself federation link https://api.auth-hub.example.com   --name auth-hub   --remote-secret "$AUTH_HUB_HASURA_SECRET"

Health-check all federated schemas in CI

nself federation status --json | jq '.[] | select(.status != "healthy")'

Sync after a remote schema migration

# On the remote project, run migrations
# Then on the consumer:
nself federation sync

Remove a deprecated remote schema

nself federation unlink https://api.legacy-backend.com

List all linked remotes as JSON

nself federation status --json | jq '[.[] | {name, url, status}]'

Environment variables

• NSELF_FEDERATION_SECRET — default remote admin secret (overridden per-link by --remote-secret)
• NSELF_ENV — default target environment

Exit codes

• 0 — success
• 1 — generic error (remote unreachable, auth failure)
• 2 — invalid arguments
• 7 — schema conflict detected during sync

Related

• nself hasura — direct Hasura metadata operations
• nself db — local database management
• nself status — overall deployment health