Skip to main content

grpcurl examples

grpcurl is useful for discovery, smoke checks, and support workflows.

Assume:

  • AFS_GRPC_ADDR='grpc.aetherfs.io:443'
  • AFS_TOKEN is a bearer token valid for the tenant and scopes you need

Add your normal connection flags as appropriate for your environment, such as TLS options or -plaintext when that is truly how the endpoint is exposed.

List services​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  "$AFS_GRPC_ADDR" list

Describe a service​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  "$AFS_GRPC_ADDR" describe aetherfs.v1.SessionService

Create a session​

This example uses the empty underlay provider.

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "empty": {},
    "initialTags": {
      "project": "docs",
      "owner": "grpc-example"
    }
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.SessionService/CreateSession

Get a session​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "sessionId": "sess_123"
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.SessionService/GetSession

Read a manifest page​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "sessionId": "sess_123",
    "pathPrefix": "/",
    "pageSize": 200,
    "includeCasExtents": true
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.FileSystemService/GetFileManifest

Subscribe to live bus traffic​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "sessionId": "sess_123",
    "topics": ["tests:*", "review:*"],
    "scope": "SESSION_ONLY",
    "replayLimit": 20
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.MessageBusService/Subscribe

Request an approval​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "sessionId": "sess_123",
    "reason": "COMMIT_TO_MAIN",
    "details": {
      "changedFiles": 14,
      "summary": "Ready for human review"
    }
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.OversightService/RequestApproval

Read session analytics​

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "sessionId": "sess_123"
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.AnalyticsService/GetSessionAnalytics

Read usage​

GetUsage is exposed on UsageService.

grpcurl \
  -H "authorization: Bearer $AFS_TOKEN" \
  -d '{
    "windowStart": "2026-03-01T00:00:00Z",
    "windowEnd": "2026-03-31T00:00:00Z",
    "granularity": "day"
  }' \
  "$AFS_GRPC_ADDR" aetherfs.v1.UsageService/GetUsage

Notes on bytes and streaming​

  • grpcurl uses JSON input, so bytes fields are base64-encoded.
  • For WriteFile, tarball sync, source archive upload, or binary-heavy message payloads, use generated clients instead of manual grpcurl sessions.
  • Reflection is the simplest way to use grpcurl, but local proto files also work if reflection is not available.