Push & Governance
hyperroute pushThe primary command for deploying schema changes. In one step, it reads your subgraph schema, composes the supergraph, validates it, checks governance policies, and activates the bundle on the router.
hyperroute push [OPTIONS]
Options
Schema Identity
Flag Type Default Description --name <NAME>String — Subgraph name — unique identifier within the federation --schema <PATH>Path — Path to the GraphQL schema file (SDL) --url <URL>String — Subgraph routing URL for the router to reach this backend
Subgraph Type
Flag Type Default Description --subgraph-type <TYPE>Enum graphqlTransport protocol: graphql, rest, or grpc
gRPC-Specific Options
Flag Type Default Description --grpc-service <NAME>String — Fully qualified gRPC service name (required for gRPC) --proto-file <PATH>Path — Path to .proto file (optional) --grpc-reflection <BOOL>Bool trueUse gRPC server reflection --grpc-tlsFlag falseEnable TLS for the gRPC connection
Environment & Configuration
Flag Type Default Description -e, --env <ENV>String devTarget environment (dev, staging, production, local) -c, --config <PATH>Path .Path to devkit.yaml --output <PATH>Path .Output directory for local mode
Deployment Mode
Flag Type Description --localFlag Local development mode — no cloud, no governance --forceFlag Force deployment — skip governance checks (audit-logged) --skip-policyFlag Skip policy checks only
Governance & CI Options
Flag Type Default Description -m, --message <MSG>String — Change description for reviewers --waitFlag — Block until approval resolves --timeout <SECS>Integer 300Wait timeout --jsonFlag — JSON output for CI/CD pipelines --statusFlag — Check environment status only --git-sha <SHA>String auto Git commit SHA for metadata --git-branch <BRANCH>String auto Git branch for metadata
Local Mode vs Cloud Mode
Local Mode (--local or --env local)
For local development. No cloud services required.
hyperroute push --local \
--name users-api \
--schema users-api.graphql \
--url http://localhost:4001 \
--subgraph-type rest
What happens:
Local file-system registry — Schemas stored in .hyperroute-registry/No Platform API — No authentication, no governance checksDirect router push — Bundle pushed to localhost:4000 via Control APIInstant activation — No proposal/approval cycle
Developer Machine
┌─────────────────────────────────────────────┐
│ │
│ hyperroute push --local │
│ │ │
│ ├─▶ .hyperroute-registry/ (schemas) │
│ ├─▶ .hyperroute/ (bundle) │
│ └─▶ localhost:4000 (router) │
│ │
│ No cloud. No auth. No approvals. │
└─────────────────────────────────────────────┘
Cloud Mode (--env dev, --env production, etc.)
For team environments and production. Full governance pipeline.
hyperroute push \
--env production \
--name users-api \
--schema users-api.graphql \
--url http://users-api:4001 \
--subgraph-type rest \
-m "Added pagination to user list endpoint"
What happens:
Cloud registry — Schemas published to S3/R2/GCS/Azure BlobPlatform API — Authenticated via HYPERROUTE_API_KEYBreaking change detection — Automatic diff against current active schemaApproval workflow — Breaking changes require human approvalBundle activation — Once approved, bundle is pushed to target routersAudit trail — Every operation recorded with timestamps and identity
┌──────────┐ ┌────────────────┐ ┌──────────────┐ ┌──────────┐
│ DevKit │───▶│ Platform API │───▶│ Registry │───▶│ Router │
│ CLI │ │ (Governance) │ │ (S3/R2/GCS) │ │ (Routerd)│
└──────────┘ └────────┬───────┘ └──────────────┘ └──────────┘
│
Breaking changes?
│
┌──── No ──┴── Yes ────┐
│ │
Auto-deploy Create proposal
exit 0 exit 10
│
Await approval
│
Re-run push
exit 0
Comparison
Aspect Local Mode Cloud Mode Flag --local or --env local--env dev/staging/productionRegistry Local filesystem Cloud storage (S3, R2, GCS) Authentication None HYPERROUTE_API_KEY env varGovernance None — always deploys Full — proposals for breaking changes Router push Direct to localhost:4000 Via Platform API Audit logging Local only Full cloud audit trail Concurrency Single developer Multi-user with locking
Governance Workflow
┌─────────────────┐ ┌──────────────┐ ┌──────────────┐
│ 1. Push Schema │────▶│ 2. Platform │────▶│ 3. Router │
│ (DevKit CLI) │ │ (Governance) │ │ (Activation) │
└────────┬────────┘ └──────┬───────┘ └──────────────┘
│ │
│ Breaking changes? │
│ │
├── No ──────────────▶│ Auto-deploy → exit 0
│ │
└── Yes ─────────────▶│ Create proposal → exit 10
│ (wait for approval)
│
│ After approval:
│ Re-run push → exit 0
Exit Codes
Code Meaning CI Action 0Success — deployed and activated Continue pipeline 10Pending approval — proposal created Wait / notify 11Rejected — proposal was denied Fail pipeline 12Policy violation — blocked by policy Fail pipeline 13Registry error — storage issue Retry 14Platform API error — governance service issue Retry 15Router activation error — router rejected bundle Investigate
CI/CD Integration Example
#!/bin/bash
EXIT_CODE=$(hyperroute push --env production \
--name products \
--schema dist/schema.graphql \
--url http://products:4001/graphql \
--json; echo $?)
case $EXIT_CODE in
0) echo "✅ Deployed successfully" ;;
10) echo "⏳ Awaiting approval — check Platform UI" ;;
11) echo "❌ Rejected" && exit 1 ;;
12) echo "❌ Policy violation" && exit 1 ;;
*) echo "❌ Error (code $EXIT_CODE)" && exit 1 ;;
esac
