Hypergraph CLI

hypergraph is a command-line interface (CLI) tool designed to facilitate various tasks related to project management, deployment, GraphQL validation, and design system integration using the Hypergraph platform.

Install

Using npm:

npm install @hgraph/cli -g

Using yarn:

yarn global add @hgraph/cli

Usage

hypergraph <auth|build|checkout|collaborator|config|create|deploy|figma|gcloud|generate|graphql|project|save> [--help] [--doc]

Commands

• auth: Commands for managing authentication and access
• build: Build a project
• checkout: Checkout a project
• collaborator: Administer project collaborators and permissions
• config: View or update configuration
• create: Create a package and other resources
• deploy: Deploy a project
• figma: Tools to handle Figma imports and design tokens
• gcloud: Configure and install tools for Google Cloud
• generate: Generate project models and resolvers using AI
• graphql: GraphQL utilities and validation tools
• project: Manage your projects
• save: Save a source file to a given project

Authentication Commands

hypergraph auth login

Access your Hypergraph account by logging in.

hypergraph auth login [--provider=<GOOGLE|GITHUB>]

Options:

• --provider=<GOOGLE|GITHUB>: Authenticate using Google or Github credentials

hypergraph auth logout

Sign out of your account.

hypergraph auth logout

hypergraph auth user

Display information of the currently logged-in user.

hypergraph auth user

Build & Deploy Commands

hypergraph build

Build a project.

hypergraph build --environment=<string> [--api=<string>] [--db-port=<number>] [--clean]

Options:

• --environment=<string> (Required): Specify the project environment
• --api=<string>: List all API services in the format "name:port" for local exposure
• --db-port=<number>: Expose the database through a specified port, if defined
• --clean: Perform a clean build by removing previous environments, cache, and config

hypergraph deploy

Deploy a project.

hypergraph deploy --environment=<string> [--create] [--clean]

Options:

• --environment=<string> (Required): Specify the deployment environment
• --create: Create missing resources like cluster, container registry, and certificates as needed
• --clean: Perform a clean build by removing previous environments, cache, and config

Project Management

hypergraph project create

Create a project.

hypergraph project create [project-name]

Arguments:

• project-name: Name of the project

hypergraph project list

List all projects.

hypergraph project list

hypergraph project remove

Remove a project.

hypergraph project remove [--project-id=<string>]

Options:

• --project-id=<string>: ID of the project to be removed

hypergraph checkout

Checkout a project.

hypergraph checkout [--project-id=<string>] [--skip-cache]

Options:

• --project-id=<string>: Specify the ID of the project to checkout
• --skip-cache: Disable cache (enabled by default)

GraphQL Utilities

hypergraph graphql validate

Validate GraphQL module structure and naming conventions using TypeScript AST analysis.

hypergraph graphql validate [--path=<string>] [--strict] [--json]

Options:

• --path=<string>: Path to the project root (defaults to current directory)
• --strict: Treat warnings as errors
• --json: Output results as JSON for CI/CD integration

Features:

• TypeScript AST-based validation for accuracy
• Intelligent computed field detection via resolver analysis
• Support for TypeORM decorators and relations
• GitIgnore support
• Syntax-highlighted error output with code snippets

hypergraph graphql rules

Display GraphQL validation rules and documentation.

hypergraph graphql rules

Figma Integration

hypergraph figma token

Set personal access token to configure Figma access.

hypergraph figma token [token]

Arguments:

• token: Your Figma personal access token

hypergraph figma user

Get current Figma user information.

hypergraph figma user

hypergraph figma import

Import design tokens and assets from a Figma URL.

hypergraph figma import <url>

Arguments:

• url: Figma file URL to import from

Collaborator Management

hypergraph collaborator add

Add a collaborator to the project.

hypergraph collaborator add [--project-id=<string>]

Options:

• --project-id=<string>: Specify the ID of the project

hypergraph collaborator list

Display contributors within a project.

hypergraph collaborator list [--project-id=<string>]

Options:

• --project-id=<string>: Project ID

hypergraph collaborator remove

Remove a collaborator from the project.

hypergraph collaborator remove [--project-id=<string>]

Options:

• --project-id=<string>: Project ID

Google Cloud Configuration

hypergraph gcloud setup

Configure the Google Cloud environment.

hypergraph gcloud setup --environment=<string>

Options:

• --environment=<string> (Required): Select the target environment

hypergraph gcloud install

Install all required libraries for Google Cloud.

hypergraph gcloud install --environment=<string>

Options:

• --environment=<string> (Required): Specify the target environment

Other Commands

hypergraph config remote

View or update remote server URL.

hypergraph config remote [url]

Arguments:

• url: Server URL

hypergraph create package

Create a package.

hypergraph create package [name]

Arguments:

• name: Name of the package

hypergraph generate

Generate project models and resolvers using AI.

hypergraph generate [--project-id=<string>]

Options:

• --project-id=<string>: Specify the ID of the project

hypergraph save

Save a source file to a given project.

hypergraph save <source-file> [--project-id=<string>]

Arguments:

• source-file: Source file(s) to upload. You may use glob patterns

Options:

• --project-id=<string>: Project ID in Hypergraph

Development

Prerequisites

• Node.js 18.x or higher
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/rintoj/hypergraph-cli.git
cd hypergraph-cli

# Install dependencies
npm install

# Build the project
npm run build

Testing

# Run tests
npm test

# Run linter
npm run lint

# Run GraphQL validation on the project itself
node dist/index.js graphql validate

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

• CI Pipeline: Runs on every push and pull request to the main branch

  • Tests on Node.js 18.x and 20.x
  • Runs linter, tests, and build
  • Validates GraphQL structure

• Release Pipeline: Automatically publishes to npm when version is bumped

  • Triggered when package.json version changes on main branch
  • Creates GitHub release with tag
  • Publishes to npm registry

Releasing

Automatic Release Process

1. Bump Version (Choose one method):

   a. Using GitHub Actions (Recommended):

   # Go to Actions tab → Version Bump → Run workflow
   # Select version type: major, minor, patch, or prerelease

   b. Using npm locally:

   npm run version:patch    # for bug fixes (0.0.1 → 0.0.2)
   npm run version:minor    # for new features (0.0.1 → 0.1.0)
   npm run version:major    # for breaking changes (0.0.1 → 1.0.0)
   npm run version:prerelease # for pre-releases (0.0.1 → 0.0.2-alpha.0)

2. Commit and Push:

   git add package.json package-lock.json
   git commit -m "chore: bump version to x.y.z"
   git push origin main

3. Automatic Release:

   • GitHub Actions detects version change
   • Runs tests and build
   • Creates GitHub release with tag vx.y.z
   • Publishes to npm as @hgraph/cli

Prerequisites for Publishing

• NPM_TOKEN: Must be set in repository secrets for npm publishing
• Permissions: Maintainer access to npm package @hgraph/cli

License

MIT

Support

For issues and feature requests, please visit the GitHub Issues page.