afh - AgenticFlow Handler CLI

CLI tool for developing, testing, and building AgenticFlow handlers.

⚠️ Beta Release - Publishing to marketplace is under development.

Installation

npm install -g @agenticflow/cli

Quick Start

# Create a new handler
afh init my-handler --yes
cd my-handler

# Start development server
npm install
afh dev

# Build package
afh build

Commands

afh init <name>

Create a new handler project from template.

afh init my-stripe-handler
afh init my-handler --stateful
afh init my-handler --yes  # Skip prompts

Options:

• --stateful - Create a stateful handler (supports checkpoints)
• --yes, -y - Skip prompts and use defaults
• --category <cat> - Handler category (ai, data, external, control, utility)

afh dev

Start development server with hot-reload and web UI.

afh dev

Opens a browser-based development environment with:

• Test Tab - Execute handlers with test values
• Inspector Tab - View handler inputs and metadata
• Trace Tab - Debug execution flow
• Docs Tab - Preview documentation
• Build Tab - Build and package for distribution

afh test

Run unit tests for your handler.

afh test

afh build

Package handler for distribution.

afh build

Creates a .afh package file ready for publishing.

Handler Structure

my-handler/
├── manifest.json     # Handler metadata
├── package.json      # Dependencies
├── src/
│   ├── index.ts      # Main handler code
│   └── utils.ts      # Development utilities
├── docs/
│   └── README.md     # Documentation
├── assets/
│   └── icon.png      # Handler icon (256x256)
└── .env              # Local secrets (gitignored)

Development with @TestValue

Use the @TestValue decorator to provide test values during development:

import { Handler, Input, StatelessHandler, StepResult } from '@flowmonkey/core';
import { TestValue } from './utils';

@Handler({
  type: 'my-handler',
  name: 'My Handler',
  category: 'utility',
})
export class MyHandler extends StatelessHandler<Input, Output> {
  @Input({ type: 'string', source: 'vault', required: true })
  @TestValue(process.env.API_KEY!)  // Stripped at build time
  apiKey!: string;

  async execute(): Promise<StepResult<Output>> {
    // Your handler logic
    return this.success({ result: 'done' });
  }
}

export default new MyHandler();

@TestValue decorators are automatically stripped from production builds.

License

MIT