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:

``sh
npm install @hgraph/cli -g
`

Using yarn:

`sh
yarn global add @hgraph/cli
`

Usage

`sh
hypergraph [--help] [--doc]
`

$3

- 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

$3

Access your Hypergraph account by logging in.

`sh
hypergraph auth login [--provider=]
`

Options:
- --provider=: Authenticate using Google or Github credentials

$3

Sign out of your account.

`sh
hypergraph auth logout
`

$3

Display information of the currently logged-in user.

`sh
hypergraph auth user
`

Build & Deploy Commands

$3

Build a project.

`sh
hypergraph build --environment= [--api=] [--db-port=] [--clean]
`

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

$3

Deploy a project.

`sh
hypergraph deploy --environment= [--create] [--clean]
`

Options:
- --environment= (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

$3

Create a project.

`sh
hypergraph project create [project-name]
`

Arguments:
- project-name: Name of the project

$3

List all projects.

`sh
hypergraph project list
`

$3

Remove a project.

`sh
hypergraph project remove [--project-id=]
`

Options:
- --project-id=: ID of the project to be removed

$3

Checkout a project.

`sh
hypergraph checkout [--project-id=] [--skip-cache]
`

Options:
- --project-id=: Specify the ID of the project to checkout
- --skip-cache: Disable cache (enabled by default)

GraphQL Utilities

$3

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

`sh
hypergraph graphql validate [--path=] [--strict] [--json]
`

Options:
- --path=: 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

$3

Display GraphQL validation rules and documentation.

`sh
hypergraph graphql rules
`

Figma Integration

$3

Set personal access token to configure Figma access.

`sh
hypergraph figma token [token]
`

Arguments:
- token: Your Figma personal access token

$3

Get current Figma user information.

`sh
hypergraph figma user
`

$3

Import design tokens and assets from a Figma URL.

`sh
hypergraph figma import
`

Arguments:
- url: Figma file URL to import from

Collaborator Management

$3

Add a collaborator to the project.

`sh
hypergraph collaborator add [--project-id=]
`

Options:
- --project-id=: Specify the ID of the project

$3

Display contributors within a project.

`sh
hypergraph collaborator list [--project-id=]
`

Options:
- --project-id=: Project ID

$3

Remove a collaborator from the project.

`sh
hypergraph collaborator remove [--project-id=]
`

Options:
- --project-id=: Project ID

Google Cloud Configuration

$3

Configure the Google Cloud environment.

`sh
hypergraph gcloud setup --environment=
`

Options:
- --environment= (Required): Select the target environment

$3

Install all required libraries for Google Cloud.

`sh
hypergraph gcloud install --environment=
`

Options:
- --environment= (Required): Specify the target environment

Other Commands

$3

View or update remote server URL.

`sh
hypergraph config remote [url]
`

Arguments:
- url: Server URL

$3

Create a package.

`sh
hypergraph create package [name]
`

Arguments:
- name: Name of the package

$3

Generate project models and resolvers using AI.

`sh
hypergraph generate [--project-id=]
`

Options:
- --project-id=: Specify the ID of the project

$3

Save a source file to a given project.

`sh
hypergraph save [--project-id=]
`

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

Options:
- --project-id=: Project ID in Hypergraph

Development

$3

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

$3

`sh


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
`

$3

`sh


Run tests

npm test

Run linter

npm run lint

Run GraphQL validation on the project itself

node dist/index.js graphql validate
`

$3

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

$3

1. Bump Version (Choose one method):

a. Using GitHub Actions (Recommended):
`sh
# Go to Actions tab → Version Bump → Run workflow
# Select version type: major, minor, patch, or prerelease
`

b. Using npm locally:
`sh
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:
`sh
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

$3

- 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.