The setup wizard is the recommended way to create or complete your HAL config. It runs interactively and guides you through project name, directory, Telegram bot token, user ID, engine/model, and session settings. It respects any existing config and only asks for what’s missing.

Explicit: run it directly:

npx @marcopeg/hal wiz

Suggested on start: when you run start (the default command) with no config or an incomplete one, HAL will detect it and (in an interactive terminal) ask if you want to run the wizard. So:

• First time in a new directory: npx @marcopeg/hal → you’ll be prompted to run the wizard.
• Config missing or missing required fields (e.g. no bot token, no user ID): same behavior.
• Non-interactive (CI, Docker, pipe): no prompt; you get the usual error and the suggestion to run wiz.

After the wizard finishes, it can write the config and then either start the bot or exit.

Before or during the wizard you’ll need:

• A Telegram bot token from @BotFather — see Creating a Telegram bot.
• Your Telegram user ID — see Finding your Telegram user ID.
• At least one supported engine installed and authenticated — see Engines.

The wizard will prompt for bot token and user ID if they’re not already in the config; you can also pre-fill them with flags (see below).

You can skip steps by providing values on the command line. When a flag is set and valid, that step is skipped and the value is applied.

Session note: true means the engine default. For Codex and Copilot, that now means per-user mode; use shared only if you explicitly want project-level shared continuation.

Examples:

# Only set engine; wizard asks for the rest
npx @marcopeg/hal wiz --engine cursor

# Pre-fill engine and model
npx @marcopeg/hal wiz --engine codex --model gpt-5.2-codex

# Pre-fill Codex shared mode explicitly
npx @marcopeg/hal wiz --engine codex --session shared

# Pre-fill bot token and user ID (e.g. for scripts)
npx @marcopeg/hal wiz --api-key 123:ABC... --user-id 7974709349

Invalid values (e.g. unknown engine) cause the wizard to prompt for that step instead of failing.

Use --reset to run the wizard as if no config existed: every step is shown and current values can be overridden.

npx @marcopeg/hal wiz --reset

• Config directory: by default the wizard uses the current working directory. Use --config <path> to run the wizard (and write config) in another directory.
• Existing config: if a config file already exists, the wizard updates it in place and keeps the same format (YAML, JSON, or JSONC). If no config exists, it creates e.g. hal.config.yaml in the config directory.
• Secrets: the wizard can store the bot token (and user IDs) in env files and put placeholders in the config so secrets aren’t committed. The docs use .env as the standard file and you should keep it out of git. The wizard writes to a single env file in the config directory (default: the current working directory, or --config when set). When an existing .env or .env.local is found, the wizard prompts you to choose which file to use (or skip env writing). Bot token placeholders are per-project (based on the project key), e.g. ${MYBOT_TELEGRAM_TOKEN}; user IDs use ${TELEGRAM_USER_ID}, ${TELEGRAM_USER_ID_2}, … See Env files — Wizard file selection for the full selection rules.

The non-interactive init command still works but is deprecated. It creates a config from a template and supports flags like --engine, --model, --cwd. Prefer wiz for interactive setup; the wizard can do everything init does and more.