System requirements

‍

Before installing HelixQA, ensure your environment meets the following minimum requirements:

‍

• Operating system: macOS 12+, Ubuntu 20.04+, or Windows 10/11 (WSL2 recommended)
• Node.js version 18 or higher
• npm version 9 or higher, or yarn 1.22+
• At least 2GB of available RAM
• Internet connection for pulling dependencies and connecting to the HelixQA API

‍

For production deployments, a minimum of 4GB RAM and a dedicated server or cloud instance is recommended.

‍

‍

Installing the HelixQA CLI

‍

The HelixQA CLI is the primary tool for initializing projects, managing environments, and deploying pipelines. Install it globally via npm:

‍

‍

npm install -g @helixqa/cli

‍

‍

Verify the installation was successful by checking the version:

‍

‍

helixqa --version

‍

If the command is not found, ensure your npm global bin directory is included in your system PATH.

‍

‍

Creating your first project

‍

Once the CLI is installed, you can scaffold a new HelixQA project with a single command:

‍

helixqa init my-project

‍

This command will:

‍

1. Create a new project directory named <my-project>.
2. Generate a default <helixqa.config.json> file with recommended settings.
3. Install all required dependencies automatically.
4. Create a sample pipeline and task configuration to help you get started.

‍

Navigate into the project directory and open the config file to review and customize settings for your environment.

‍

‍

Connecting to your workspace

‍

To link your local project to your HelixQA workspace, authenticate using the CLI:

‍

helixqa login

‍

‍

This will open a browser window prompting you to sign in. Once authenticated, your workspace credentials are stored locally in a secure config file at ~/.helixqa/credentials.

‍

To link an existing project to a specific workspace:

‍

‍helixqa workspace link --id YOUR_WORKSPACE_ID

‍

‍

Environment configuration

‍

HelixQA uses environment files to manage configuration across different deployment stages. Create a .env file in your project root and define your environment variables:

‍

1HELIXQA_API_KEY=your_api_key_here
2HELIXQA_WORKSPACE_ID=your_workspace_id
3HELIXQA_ENV=development

‍

Never commit your .env file to version control. Add it to your <.gitignore> to prevent accidental exposure of credentials.

‍

‍

Running locally

‍

To start the HelixQA development server locally: helixqa dev

‍

The development server watches for changes to your pipeline configurations and task definitions, automatically reloading on save. You can access the local dashboard at <http://localhost:3000> to monitor task execution in real time.

‍

‍

Deploying to production

‍

When you are ready to deploy, run:

‍

helixqa deploy --env production

‍

This command validates your configuration, bundles your pipelines, and pushes them to the HelixQA cloud infrastructure. Deployment typically completes within 30 seconds for standard projects.