In Forge&Hive projects, the typical development workflow involves creating and testing tasks via the CLI before integrating them into your application. This approach accelerates development by eliminating the need to switch between tools like browsers or Postman.

This tutorial will guide you through setting up a hello world project and running your first Forge&Hive task.

Installing the Forge&Hive CLI

First, install the Forge&Hive CLI globally:

pnpm i -g @forgehive/forge-cli

Note: You can also use npm (npm install -g @forgehive/forge-cli) or yarn (yarn global add @forgehive/forge-cli).

Verify your installation:

forge info

You should see output similar to:

===============================================
============ Forge CLI Information ============
===============================================

Version: 0.3.10

❌ No forge.json file found in current directory.
   Run "forge init" to create a new Forge project.

===============================================

Note: The "No forge.json file found" message is expected at this stage. We'll create the project and initialize it in the next steps.

Creating a New Project

1.- Create a project directory and initialize your package:

mkdir hello-world-project
cd hello-world-project
pnpm init

2.- Install the required Forge&Hive packages:

pnpm add @forgehive/task @forgehive/schema

3.- Initialize your Forge&Hive project:

forge init

This command creates a forge.json file, completing your project setup. The forge.json file contains the configuration paths that define where logs, fixtures, and tasks will be created in your project.

For AI Copilot Users (Recommended)

If you're working with an AI copilot (Claude, GitHub Copilot, Cursor, etc.) - and since it's 2025, you probably should be - download the ForgeHive LLM guide to help your AI assistant understand the framework:

forge docs:download

This downloads the comprehensive LLM guide to docs/forge.md in your project. Ask your AI copilot to:

"Please read the docs/forge.md file and add it to your memory/context. This contains the complete ForgeHive task management guide that will help you assist me with creating, running, and managing tasks in this project."

Your AI assistant will then be able to provide much better guidance on ForgeHive patterns, task creation, boundary design, and best practices.

Creating and Running Your First Task

Create a task using the Forge&Hive CLI:

forge task:create samples:helloWorld

This generates a new file at src/tasks/samples/helloWorld.ts. Run the task with:

forge task:run samples:helloWorld

You should see output similar to:

===============================================
Running: task:run samples:helloWorld {}
===============================================
Creating profiles.json
===============================================
No profile found, logs will not be sent to remote API
===============================================
input: {}
boundaries: {
  setMetadata: [AsyncFunction: a] {
    getTape: [Function (anonymous)],
    setTape: [Function (anonymous)],
    getMode: [Function (anonymous)],
    setMode: [Function (anonymous)],
    startRun: [Function (anonymous)],
    stopRun: [Function (anonymous)],
    getRunData: [Function (anonymous)]
  },
  setMetrics: [AsyncFunction: a] {
    getTape: [Function (anonymous)],
    setTape: [Function (anonymous)],
    getMode: [Function (anonymous)],
    setMode: [Function (anonymous)],
    startRun: [Function (anonymous)],
    stopRun: [Function (anonymous)],
    getRunData: [Function (anonymous)]
  }
}
===============================================
Outcome: Success
===============================================
Result { status: 'Ok' }
===============================================

Note: The "Creating profiles.json" and "No profile found" messages are normal for a new project. Profiles and remote log sending are covered in upcoming tutorials.

Congratulations! You've successfully created and run your first Forge&Hive task.

Next Steps