Official CLI & Declarative Schema Sync

Manage your authorization schema as code. Define roles, permissions, and OAuth providers in a declarative manifest, preview changes with plan diffs, and sync automatically via CI/CD using @hvt/cli.

1. Installation

The official HVT CLI is published on npm as @hvt/cli. You can run it instantly using npx without installing anything locally:

bash
npx @hvt/cli --help

Or install it globally for direct hvt terminal access:

bash
# Install globally via npm
npm install -g @hvt/cli

# Verify version
hvt --version

2. Initialize your schema manifest

In the root directory of your project, run init to generate a starter hvt.schema.json file:

bash
# Create starter schema with default Google & GitHub OAuth
npx @hvt/cli init

# Or explicitly choose OAuth providers
npx @hvt/cli init --providers google,github,discord

# Or include all supported providers (Google, GitHub, Discord, Apple, Microsoft, GitLab)
npx @hvt/cli init --all-providers
Supported OAuth providers
HVT natively supports google, github, discord, apple, microsoft, and gitlab. When running init, starter templates with redirect URIs are populated automatically.

3. Configure environment credentials

The CLI reads your Project ID and Management Key from standard environment variables, looking automatically in your current shell, .env, or .env.local:

bash
# .env or .env.local
HVT_PROJECT_ID="b5540592-38fd-4d42-9538-c125716f31f4"
HVT_MANAGEMENT_KEY="hvt_mgmt_test_1a2b3c4d5e6f7a8b9c0d"

# OAuth provider secrets referenced via ${VAR} in schema
GOOGLE_CLIENT_ID="123456789-abc.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-your-secret-here"
GITHUB_CLIENT_ID="Iv1.your-client-id"
GITHUB_CLIENT_SECRET="your-github-secret-here"
Management key security
The management key (hvt_mgmt_*) grants administrative provisioning rights to your project schema. Never expose it in client-side code, git commits, or prefix it with NEXT_PUBLIC_.

4. The declarative schema specification

The schema manifest (hvt.schema.json or hvt.schema.yaml) declares the desired state of your application’s authorization model:

json
{
  "$schema": "https://hvts.app/schemas/hvt.schema.v1.json",
  "schema_version": 1,
  "permissions": [
    {
      "slug": "documents:create",
      "name": "Create Documents",
      "description": "Allows creating new documents"
    },
    {
      "slug": "documents:read",
      "name": "Read Documents",
      "description": "Allows viewing documents"
    },
    {
      "slug": "documents:delete",
      "name": "Delete Documents",
      "description": "Allows deleting documents"
    },
    {
      "slug": "team:invite",
      "name": "Invite Team Members",
      "description": "Allows inviting members to the organization"
    }
  ],
  "roles": [
    {
      "slug": "admin",
      "name": "Administrator",
      "description": "Full access to all project resources",
      "is_default_signup": false,
      "permissions": [
        "documents:create",
        "documents:read",
        "documents:delete",
        "team:invite"
      ]
    },
    {
      "slug": "member",
      "name": "Member",
      "description": "Standard team member with document authoring rights",
      "is_default_signup": true,
      "permissions": [
        "documents:create",
        "documents:read"
      ]
    }
  ],
  "social_providers": [
    {
      "provider": "google",
      "client_id": "${GOOGLE_CLIENT_ID}",
      "client_secret": "${GOOGLE_CLIENT_SECRET}",
      "allowed_redirect_uris": [
        "http://localhost:3000/auth/callback",
        "https://app.example.com/auth/callback"
      ],
      "is_active": true
    },
    {
      "provider": "github",
      "client_id": "${GITHUB_CLIENT_ID}",
      "client_secret": "${GITHUB_CLIENT_SECRET}",
      "allowed_redirect_uris": [
        "http://localhost:3000/auth/callback",
        "https://app.example.com/auth/callback"
      ],
      "is_active": true
    }
  ]
}

Key Manifest Properties

FieldTypeDescription
schema_versionnumberSchema specification version (currently 1).
permissionsarrayList of granular action slugs (documents:create, team:invite) and human-readable names.
rolesarrayRole definitions bundling permission slugs. Set is_default_signup: true on the role automatically assigned to self-service signups.
social_providersarrayOAuth 2.0 provider configurations. Supports ${ENV_VAR} interpolation so secrets stay out of version control.

5. Verify connectivity (whoami)

Verify that your management key and project ID are valid and connected to HVT Cloud:

bash
npx @hvt/cli whoami
text
✔ Connected to HVT
  API Endpoint:   https://api.hvts.app
  Project ID:     b5540592-38fd-4d42-9538-c125716f31f4
  Environment:    test
  Management Key: hvt_mgmt_test_1a2b...

6. Preview changes (schema plan)

Before mutating anything in production, run schema plan. This performs a transactional dry run against HVT Cloud (?dry_run=true) and prints the exact diff of what will be created, updated, or removed:

bash
# Preview planned changes against HVT Cloud
npx @hvt/cli schema plan

# Output structured JSON for CI automations
npx @hvt/cli schema plan --json
text
🔍 Proposed Schema Changes (Dry Run):

  Permissions:
    + documents:create (Create Documents)
    + documents:read (Read Documents)
    + documents:delete (Delete Documents)
    + team:invite (Invite Team Members)

  Roles:
    + admin (Administrator) -> [documents:create, documents:read, documents:delete, team:invite]
    + member (Member, default signup) -> [documents:create, documents:read]

  Social Providers:
    + google (active, 2 redirect URIs)
    + github (active, 2 redirect URIs)

Plan: 8 to create, 0 to reconcile, 0 to prune.
Dry run complete. No database changes were made.

7. Synchronize live (schema sync)

When you are satisfied with the preview, run schema sync to apply the changes to HVT:

bash
# Apply schema changes to HVT Cloud
npx @hvt/cli schema sync

# Apply and delete omitted roles/permissions with confirmation prompt
npx @hvt/cli schema sync --prune

# Non-interactive CI/CD mode (automatically confirms pruning)
npx @hvt/cli schema sync --prune --yes
Automatic runtime client key provisioning
On the first sync of a new project, hvt schema sync automatically issues a runtime client key and writes it directly to your .env.local file as NEXT_PUBLIC_HVT_CLIENT_KEY, so your frontend is immediately ready to run.

8. CI/CD GitOps workflow

Store hvt.schema.json in your git repository. Add a GitHub Actions workflow to preview diffs on Pull Requests and synchronize on merge:

yaml
name: HVT Schema GitOps

on:
  pull_request:
    paths:
      - 'hvt.schema.json'
  push:
    branches:
      - main
    paths:
      - 'hvt.schema.json'

jobs:
  schema-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # On PR: dry-run plan preview
      - name: Preview Schema Changes
        if: github.event_name == 'pull_request'
        run: npx @hvt/cli schema plan
        env:
          HVT_PROJECT_ID: ${{ secrets.HVT_PROJECT_ID }}
          HVT_MANAGEMENT_KEY: ${{ secrets.HVT_MANAGEMENT_KEY }}

      # On main push: apply changes with pruning
      - name: Apply Schema to HVT
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: npx @hvt/cli schema sync --prune --yes
        env:
          HVT_PROJECT_ID: ${{ secrets.HVT_PROJECT_ID }}
          HVT_MANAGEMENT_KEY: ${{ secrets.HVT_MANAGEMENT_KEY }}
          GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
          GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
          GITHUB_CLIENT_ID: ${{ secrets.GITHUB_CLIENT_ID }}
          GITHUB_CLIENT_SECRET: ${{ secrets.GITHUB_CLIENT_SECRET }}

9. CLI options and flags reference

FlagCommandsDescription
--pruneschema syncDeletes manifest-managed roles, permissions, and providers that are omitted from your schema file.
-y, --yesschema syncBypasses interactive confirmation for --prune. Required for non-interactive CI/CD runs.
--issue-client-keyschema syncForces minting an additional runtime client key even if one is already active.
-p, --project <id>AllExplicit HVT Project UUID (overrides HVT_PROJECT_ID env var).
-k, --key <key>AllExplicit Management Key (overrides HVT_MANAGEMENT_KEY env var).
-s, --schema <path>plan, syncPath to schema file (defaults to hvt.schema.json or hvt.schema.yaml).
--api-url <url>AllCustom API endpoint URL (defaults to https://api.hvts.app).
--jsonAllOutputs raw JSON for scripting, automated CI jobs, and AI coding agents.