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:
Or install it globally for direct hvt terminal access:
2. Initialize your schema manifest
In the root directory of your project, run init to generate a starter hvt.schema.json file:
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:
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:
Key Manifest Properties
| Field | Type | Description |
|---|---|---|
schema_version | number | Schema specification version (currently 1). |
permissions | array | List of granular action slugs (documents:create, team:invite) and human-readable names. |
roles | array | Role definitions bundling permission slugs. Set is_default_signup: true on the role automatically assigned to self-service signups. |
social_providers | array | OAuth 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:
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:
7. Synchronize live (schema sync)
When you are satisfied with the preview, run schema sync to apply the changes to HVT:
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:
9. CLI options and flags reference
| Flag | Commands | Description |
|---|---|---|
--prune | schema sync | Deletes manifest-managed roles, permissions, and providers that are omitted from your schema file. |
-y, --yes | schema sync | Bypasses interactive confirmation for --prune. Required for non-interactive CI/CD runs. |
--issue-client-key | schema sync | Forces minting an additional runtime client key even if one is already active. |
-p, --project <id> | All | Explicit HVT Project UUID (overrides HVT_PROJECT_ID env var). |
-k, --key <key> | All | Explicit Management Key (overrides HVT_MANAGEMENT_KEY env var). |
-s, --schema <path> | plan, sync | Path to schema file (defaults to hvt.schema.json or hvt.schema.yaml). |
--api-url <url> | All | Custom API endpoint URL (defaults to https://api.hvts.app). |
--json | All | Outputs raw JSON for scripting, automated CI jobs, and AI coding agents. |