Installation

Install an SDK

Official SDKs are available for four languages. They share one design: a Halyard client for the REST API and a Worker that runs your task handlers. All are versioned with the API, so SDK 3.x talks to API v3.

npm install @halyard/node

pip install halyard

go get halyard.example/go/halyard@v3

gem install halyard

Pin the major version so a future v4 never arrives as a surprise:

{  "dependencies": {    "@halyard/node": "^3.4.2"  }}

# requirements.txthalyard>=3.4,<4

require halyard.example/go/halyard v3.3.1

# Gemfilegem "halyard", "~> 3.2"

Install the CLI

The halyard command line tool runs workers locally against the sandbox, applies your halyard.yaml on deploy and tails jobs live. It is a single binary with no runtime dependencies.

brew install halyard-labs/tap/halyard

curl -fsSL https://get.halyard.example/cli | sh

npm install --global @halyard/cli

Then sign in once. The CLI stores a test key for the project you pick:

$halyard login› Opening https://app.halyard.example/cli/authorize?code=QKVM-7TXR› Waiting for confirmation in the browser…✓ Signed in as maya@northwind-labs.example✓ Project my-app · test key saved to ~/.halyard/credentials

Everyday commands

# Run the worker in src/worker.ts, reload on changehalyard dev # Apply halyard.yaml to the live environmenthalyard deploy --env live # Follow failures on the emails queuehalyard jobs tail --queue emails --status failed

Environment variables

The SDKs and the CLI read configuration from the environment, so the same code runs locally, in CI and in production. Arguments you pass in code always win over variables.

Project layout

A typical project keeps one halyard.yaml at the root, a worker entry point and one file per task. The CLI looks for halyard.yaml in the current directory and its parents.

# halyard.yamlversion: 3project: my-app queues:  emails:    concurrency: 20    rate_limit: 50/s  media:    concurrency: 8    timeout: 10m worker:  entry: src/worker.ts  concurrency: 5

Requirements

Workers need outbound HTTPS to api.halyard.example on port 443. No inbound ports are needed: workers pull jobs, Halyard never connects to them.

Verify the install

Run halyard doctor to check the CLI, your key and network access in one go:

$halyard doctor✓ CLI 3.4.1 (latest)✓ HALYARD_KEY found · test mode · scopes: all✓ api.halyard.example reachable · 38 ms✓ halyard.yaml valid · 2 queues, 0 schedules! Node.js SDK 3.3.0 installed, 3.4.2 available

Or from code, retrieve the account the key belongs to:

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY);const me = await halyard.account.retrieve(); console.log(me.environment, me.project); // test my-app

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"])me = halyard.account.retrieve() print(me.environment, me.project)  # test my-app

client := halyard.New(os.Getenv("HALYARD_KEY"))me, err := client.Account.Retrieve(ctx)if err != nil {	log.Fatal(err)}fmt.Println(me.Environment, me.Project) // test my-app

halyard = Halyard::Client.new(ENV.fetch("HALYARD_KEY"))me = halyard.account.retrieve puts me.environment, me.project # test my-app