hasura-cli

2.38.0 verified Sat Apr 25 auth: no javascript

An npm package that automatically installs and wraps the Hasura CLI binary in an isolated manner, currently at v2.38.0. It mirrors the official Hasura CLI releases (Go binary) and is auto-published on new Hasura releases. Key differentiator: it allows per-project installation with different versions, avoiding global binary management and ensuring team consistency. Supports alpha, beta, and latest release channels via npm tags. Requires Node.js >= 16.

Common errors

error Cannot find module 'hasura-cli' ↓

cause Attempting to require('hasura-cli') in Node.js thinking it's a library.

fix

This is a binary-only package. Use 'npx hasura' or add to scripts.

error hasura: command not found ↓

cause Binary not installed or not in PATH after global install without proper npm prefix.

fix

Reinstall globally: 'npm install -g hasura-cli' or use 'npx hasura'.

error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/hasura-cli' ↓

cause Global install without sudo or incorrect npm prefix on Linux/macOS.

fix

Use 'sudo npm install -g hasura-cli' or configure npm prefix for user.

error Error: Failed to download Hasura CLI binary for platform darwin/arm64 ↓

cause Platform detection issue or missing platform support (e.g., Apple Silicon not supported in older versions).

fix

Update to latest version of hasura-cli (>=2.0.0). Alternatively, set environment variable HASURA_BINARY_PATH to a manually downloaded binary.

error SyntaxError: Unexpected token '.' in JSON at position 0 ↓

cause Corrupted binary download or incomplete installation.

fix

Delete node_modules and reinstall: 'rm -rf node_modules && npm install'.

Warnings

breaking Versioning follows Hasura CLI releases, not semantic versioning of this package. v2.38.0 corresponds to Hasura CLI v2.38.0. ↓

fix Check Hasura CLI changelog for breaking changes between versions, not this package's changelog.

deprecated Installation via 'npm install --save-dev hasura-cli' without a tag may install an outdated version if the 'latest' tag is behind. ↓

fix Always specify a tag or version: 'npm install --save-dev hasura-cli@latest' or 'npm install --save-dev hasura-cli@2.38.0'.

gotcha Package does not expose a JavaScript API; it only provides a binary. Attempting to require('hasura-cli') returns an empty object. ↓

fix Use the binary via npx, shell scripts, or npm scripts. Do not attempt to import.

gotcha Binary download may fail in restricted network environments (e.g., CI with no internet access). ↓

fix Pre-download the binary and place it at node_modules/.bin/hasura, or set environment variable HASURA_BINARY_PATH to a local path.

gotcha Alpha and beta versions may be unstable. The 'alpha' and 'beta' npm tags refer to Hasura's pre-release versions. ↓

fix Use '@latest' for stable releases unless you need to test pre-release features.

Install

npm install hasura-cli

yarn add hasura-cli

pnpm add hasura-cli

Imports

hasura
wrong
```
import hasura from 'hasura-cli'
```
correct
```
npx hasura ...
```
hasura-cli provides a binary, not a JS module. Use npx or add to scripts in package.json.

default

wrong

const hasura = require('hasura-cli');

correct

const { execSync } = require('child_process'); execSync('npx hasura --version');

No default export; the package only installs the binary.

hasura

wrong

import { hasura } from 'hasura-cli'

correct

// In package.json scripts: "hasura": "hasura"

Add to npm scripts to use the binary directly; no named export.

Quickstart

Shows installation, version check, project init, and migration apply using the hasura binary via npx.

// 1. Install as devDependency (or globally)
npm install --save-dev hasura-cli@latest

// 2. Verify installation
npx hasura version

// 3. Initialize a Hasura project
npx hasura init my-project --endpoint https://your-hasura-instance.com

// 4. Apply migrations or metadata
cd my-project
npx hasura migrate apply
npx hasura metadata apply