hailer-sdk init

Initialize a new Hailer project with proper structure and configuration.

Usage

hailer-sdk init

Flags

init is interactive, but any prompt can be pre-answered with a flag (useful for scripting / CI):

Flag	Effect
--project-name <name>	Project name (skips the prompt).
--workspace <id>	Target workspace id (must be one you own or admin).
--email <email> / --password <pw>	Credentials (skips the prompts).
--user-api-key <key>	Authenticate with an API key instead of email/password (enables remote MCP).
--mcp-url <url>	Remote MCP server URL. Requires --user-api-key.
--bot / --no-bot	Create / skip the bot account (skips the prompt).
--mcp / --no-mcp	Set up / skip the MCP server (skips the prompt).
--hailer-studio	Adjust the generated project for Hailer Studio.
--verbose	Detailed logging.

Description

The init command is an interactive wizard that guides you through setting up a new Hailer project. It handles authentication, workspace selection, optional bot account creation, optional MCP server setup, and creates all necessary project files and configurations.

Interactive Steps

1. Project name - Choose a name for your project
2. API URL - Select which Hailer API to connect to (cloud or local development)
3. Email - Enter your Hailer account email (skipped if --user-api-key provided)
4. Password - Enter your Hailer account password (skipped if --user-api-key provided)
5. Workspace selection - Choose from the workspaces where you're an owner or admin, or create a new one
6. Bot account creation - Optionally create a bot user for automated workspace operations
7. MCP server setup - Optionally set up the Model Context Protocol server for TUI integration. With --user-api-key, sets up a remote MCP connection; otherwise sets up a local MCP server (local MCP requires a bot account)

What it Creates

The command generates a complete project structure:

my-project/
├── workspace/           # Workflow configs (generated on `npm run pull`)
│   └── hailer.d.ts      # Type definitions (copied in at init)
├── .mcp.json            # MCP configuration (if MCP enabled; git-ignored)
├── .env.local           # MCP server credentials (local MCP only; git-ignored)
├── docs/                # Copy of SDK documentation
├── .env                 # Environment variables (password or user API key; git-ignored)
├── .gitignore           # Excludes .env and other sensitive files
├── config.json          # Workspace configuration
├── package.json         # Node.js project configuration with useful scripts
├── tsconfig.json        # TypeScript configuration
├── vitest.config.ts     # Test runner configuration
├── CLAUDE.md            # TUI agent instructions
└── README.md            # Project documentation

# On `npm install`, the postinstall step also copies from @hailer/mcp:
#   .claude/     # TUI configuration
#   .opencode/   # OpenCode configuration
#   CLAUDE.md    # refreshed to the latest agent instructions

Generated npm scripts

The package.json includes these helpful scripts:

Workspace Management:

• npm run pull - Pull workflows from Hailer
• npm run push - Push all configurations to Hailer
• npm run workflows-push - Push only workflow configurations
• npm run workflows-sync - Create/delete workflows
• npm run fields-push - Push only field configurations
• npm run phases-push - Push only phase configurations
• npm run templates-push - Push only template configurations
• npm run templates-sync - Create/delete document templates
• npm run groups-push - Push only group configurations
• npm run teams-push - Push only team configurations
• npm run insights-push - Push only insights configurations
• npm run apps-push - Push only app configurations

Every push/sync script also has a :force variant (e.g. push:force, fields-push:force, workflows-sync:force) that skips delete confirmations.

Testing & maintenance:

• npm test / npm run test:watch / npm run test:ui - Run function-field tests (Vitest)
• npm run sdk-update - Update @hailer/sdk and re-run postinstall
• postinstall - Copies .claude/ and .opencode/ config and refreshes type definitions (runs automatically on npm install)

MCP Server (local MCP only):

• npm run mcp-start - Start the MCP server
• npm run mcp-update - Update @hailer/mcp package and refresh .claude and .opencode directories

Note: Remote MCP setups do not include mcp-start script — the MCP server runs remotely.

Bot Account (Optional)

During initialization, you can choose to create a bot account for your workspace. The bot account:

• Is registered as user Bot Botinen with email <workspace-name>_<4-digit suffix>@botinen.fi
• Gets a randomly generated secure password (32 characters)
• Is added to the 🤖 Bots team in your workspace (created if it doesn't exist)
• Is invited with the admin role
• Its credentials replace your personal credentials in the project's .env file (and, for local MCP, in .env.local)

This is useful for:

• Separating bot actions from personal user actions

Note: The bot credentials are displayed once during initialization. But you can see the bot's email in the config.json file and the password in .env file.

Declining the bot in the interactive flow means a local MCP server can't be set up — local MCP authenticates with the bot's credentials.

MCP Server Setup (Optional)

The MCP (Model Context Protocol) server enables your TUI to interact with your Hailer workspace programmatically. There are two modes: local and remote.

Local MCP (requires a bot account)

When enabled, the initialization:

• Creates .mcp.json — an npx mcp-remote client pointing at the local server (http://localhost:3030/api/mcp)
• Creates .env.local with the bot account's credentials the server authenticates with
• Adds mcp-start and mcp-update npm scripts to package.json

Local MCP is only set up when a bot account exists — in the interactive flow, declining the bot skips it.

Starting the Local MCP Server

cd my-project
npm install
npm run mcp-start

The npm install step will automatically install all dependencies including @hailer/mcp and run the postinstall script to copy .claude/ and .opencode/ configuration.

Then open a new terminal and start your TUI to interact with your workspace through the MCP server.

Updating the Local MCP Server

npm run mcp-update

Note: After updating, restart the MCP server and any running TUI agents that depend on it.

Remote MCP (user API key authentication)

When --user-api-key is provided, MCP is configured to connect to a remote server instead of running locally.

When enabled, the initialization:

• Creates .mcp.json — an npx mcp-remote client pointing at <mcp-url>/api/mcp?apiKey=<your-key> (git-ignored)
• Prompts for the remote MCP server URL (or uses --mcp-url flag)
• No .env.local or local MCP scripts are created

Getting Started with Remote MCP

cd my-project
npm install

Then start your TUI — it will connect to the remote MCP server automatically. No need to start anything locally.

The .mcp.json file contains the remote server URL with your API key. It is git-ignored for security. If the URL or key changes, update .mcp.json and restart your TUI.

Next Steps

After initialization:

1. Navigate to your project:

   cd my-project
   npm install

2. Pull your workspace configuration:

   npm run pull

3. (Optional) If you set up a local MCP server, start it:

   npm run mcp-start

   For remote MCP, just start your TUI — it connects automatically.

4. Start developing with type-safe workflow definitions!

API URL Selection

During initialization, you'll be prompted to select an API URL:

• Hailer cloud (https://api.hailer.com) - Production Hailer API (default)
• Hailer local (https://api.hailer.local.gd/) - Local development environment

The selected API URL is saved to config.json and used for all subsequent SDK commands.

For local development:

• The SDK automatically detects local environments (URL contains "local")
• Self-signed SSL certificates are automatically accepted for local APIs
• Useful for testing changes before deploying to production

User API Key Authentication

As an alternative to email/password authentication, you can use a user API key:

hailer-sdk init --user-api-key "your-api-key-here"

# With remote MCP server:
hailer-sdk init --user-api-key "your-api-key-here" --mcp-url "https://mcp.example.com"

Note: --mcp-url requires --user-api-key. It specifies the remote MCP server URL to connect to.

How it Works

When --user-api-key is provided:

• Email and password prompts are skipped
• Authentication uses the user API key
• You can still create a bot account (recommended for MCP server)

MCP Server Requirement

• Local MCP requires a bot account — its bot credentials are written to .env.local and used to authenticate. In the interactive flow, declining the bot skips local MCP setup.
• Remote MCP is configured when you authenticate with --user-api-key (optionally with --mcp-url); no local server runs.
• The --mcp / --no-mcp flags force MCP setup on or off non-interactively.

Generated Files

The .env and config.json files are configured based on your authentication method:

With email/password (or bot account):

# .env
HAILER_PASSWORD="your-password"

# config.json
{
  "email": "your-email@example.com",
  "password": "HAILER_PASSWORD",
  "workspaceId": "...",
  "apiUrl": "..."
}

With user API key only (no bot):

# .env
HAILER_USER_API_KEY="your-api-key"

# config.json
{
  "workspaceId": "...",
  "apiUrl": "...",
  "userApiKey": "HAILER_USER_API_KEY"
}

Notes

• The .env file contains your credentials - never commit this to version control
• The .env.local file (local MCP only) contains MCP server credentials - git-ignored
• The .mcp.json file is always git-ignored (it can contain an API key)
• The generated .gitignore excludes .env, .env.local, .mcp.json, .claude/, and .opencode/
• Type definitions are copied to your project for IDE support
• Bot credentials are displayed only once during initialization - save them securely!
• The MCP server is installed as an npm package (@hailer/mcp) in your node_modules/
• The apiUrl field in config.json determines which API all commands will use

Troubleshooting

MCP Server Setup Fails

If the MCP server setup fails during initialization:

• Check your network connection (npm package must be downloaded)
• Ensure you have Node.js 18+ installed
• Verify that @hailer/mcp package is available on npm
• Try running npm install manually after initialization to trigger the postinstall script

Bot Account Creation Fails

If bot account creation fails:

• You can continue with your personal credentials
• The project will still be initialized successfully
• You can manually create a bot account later through the Hailer UI

Workspace Creation Fails

If creating a new workspace fails:

• Select an existing workspace instead
• Check your account permissions
• Verify your network connection