gtc wizard

Overview

The gtc wizard command creates new Greentic bundles from wizard answers. It scaffolds the complete bundle structure including configuration files, provider setups, and app templates.

Usage

gtc wizard [OPTIONS]

Options

Option	Description
--schema	Print the current launcher AnswerDocument schema
--answers <FILE | URL>	Path or URL to a JSON AnswerDocument envelope. Supports local paths and remote http:// / https:// URLs.
--dry-run	Preview generated files without writing
--out <DIR>	Override output directory for the wizard run
--emit-answers <FILE>	Emit a portable JSON AnswerDocument
--yes	Skip interactive confirmation for apply
--non-interactive	Allow execution in non-interactive contexts

Wizard AnswerDocument

gtc wizard automation uses JSON AnswerDocument files. Ask the CLI for the live schema before generating or editing answers:

gtc wizard --schema

The schema includes the launcher envelope plus embedded schemas for delegated bundle and pack wizard runs. A minimal bundle AnswerDocument looks like this:

wizard-answers.json

{
  "wizard_id": "greentic-dev.wizard.launcher.main",
  "schema_id": "greentic-dev.launcher.main",
  "schema_version": "1.0.0",
  "locale": "en",
  "answers": {
    "selected_action": "bundle",
    "delegate_answer_document": {
      "wizard_id": "greentic-bundle.wizard.run",
      "schema_id": "greentic-bundle.wizard.answers",
      "schema_version": "1.0.0",
      "locale": "en",
      "answers": {
        "bundle_name": "My Digital Worker",
        "bundle_id": "my-digital-worker",
        "output_dir": "./my-digital-worker",
        "extension_providers": ["messaging-webchat"],
        "app_packs": ["support-bot"],
        "capabilities": ["greentic.cap.bundle_assets.read.v1"]
      },
      "locks": {
        "execution": "execute"
      }
    }
  },
  "locks": {
    "execution": "execute"
  }
}

Capabilities

The delegated bundle answers.capabilities array controls bundle-level features that are enabled when the bundle is created. Capabilities determine what additional scaffolding the wizard performs beyond the standard bundle structure.

create-answers.json

{
  "answers": {
    "delegate_answer_document": {
      "answers": {
        "capabilities": ["greentic.cap.bundle_assets.read.v1"]
      }
    }
  }
}

Available capabilities:

Capability	Description
greentic.cap.bundle_assets.read.v1	Enables bundle-level asset overrides. When present, the wizard auto-scaffolds eligible webchat-gui skin assets from extension packs into the bundle’s assets/ directory.

When greentic.cap.bundle_assets.read.v1 is included, the generated bundle will contain an assets/ directory with eligible files copied from extension packs (e.g., webchat-gui skins and configuration). These bundle-level files can be customized and will override pack defaults at runtime.

نصيحة

The capabilities array is written into bundle.yaml and is also respected by gtc setup when configuring the bundle later. See the gtc setup capabilities section for details on runtime behavior.

Generated Structure

Running the wizard generates:

my-digital-worker/
├── bundle.yaml                 # Bundle workspace state
├── providers/                  # Compatibility materialization directory for extension .gtpack files
│   ├── messaging/
│   │   ├── messaging-telegram.gtpack
│   │   └── messaging-slack.gtpack
│   └── events/
│       ├── events-webhook.gtpack
│       └── events-timer.gtpack
├── apps/
│   └── support-bot/
│       ├── app.yaml
│       └── flows/
│           └── on_message.ygtc
├── tenants/
│   └── demo/
│       ├── tenant.gmap
│       └── teams/
│           └── default/
│               └── team.gmap
└── seeds.yaml

Examples

Demo Catalog Bundles

The greentic-demo repository publishes a *-create-answers.json and a *-setup-answers.json for every demo in its release artifacts. Use them directly to create a local bundle that you can keep editing afterwards:

gtc wizard --answers https://github.com/greenticai/greentic-demo/releases/latest/download/deep-research-demo-create-answers.json

Then continue with setup and start:

gtc setup ./deep-research-demo-bundle --answers https://github.com/greenticai/greentic-demo/releases/latest/download/deep-research-demo-setup-answers.json
gtc start ./deep-research-demo-bundle

Substitute the demo ID for any of the published demos (quickstart, hr-onboarding, helpdesk-itsm, sales-crm, supply-chain, redbutton, cloud-deploy-demo, weather-mcp-demo, …). The full catalog with descriptions and required credentials lives on the Running Demos page.

نصيحة

The wizard performs capability-based dependency resolution. When the demo’s create-answers document references an extension that declares required_capabilities (e.g. messaging extensions needing greentic:state/state-store), the wizard automatically adds a satisfying pack such as state-memory to the generated bundle — you do not have to list it manually.

Basic Usage

# Interactive mode
gtc wizard

# With answers file
gtc wizard --answers wizard-answers.json

Preview Mode

# See what would be generated
gtc wizard --answers wizard-answers.json --dry-run

Remote Answers File

The --answers flag accepts http:// and https:// URLs, making it straightforward to store shared answer documents in a central location and reference them from CI/CD pipelines.

# Fetch answers from a remote URL
gtc wizard --answers https://config.example.com/teams/support/wizard-answers.json

# Combine with dry-run to preview before generating
gtc wizard --answers https://config.example.com/teams/support/wizard-answers.json --dry-run

نصيحة

Remote URL support is useful in CI/CD pipelines where wizard answers are stored in a shared repository or artifact server and pulled at build time.

Custom Output Directory

gtc wizard --answers wizard-answers.json --out ./my-project

Bundle Capabilities

The wizard prompts for optional bundle capabilities that enable additional features. Each capability unlocks a specific set of assets and behaviors in the generated bundle.

Interactive Prompts

When running gtc wizard interactively, you will see:

? Enable bundle-level assets (./assets/)? [Y/n]
? Enable OAuth login for WebChat GUI? [y/N]
? Enable multi-language for WebChat GUI? [y/N]
? Enable embeddable WebChat widget? [y/N]

Capability Reference

Prompt	Capability ID	What It Does
Enable bundle-level assets	greentic.cap.bundle_assets.read.v1	Creates the ./assets/ directory and scaffolds eligible webchat assets from extension packs
Enable OAuth login for WebChat GUI	greentic.cap.webchat.oauth.v1	Adds OAuth/OIDC authentication provider configuration to tenant config files
Enable multi-language for WebChat GUI	greentic.cap.webchat.i18n.v1	Enables the locale picker in WebChat and scaffolds locale JSON files under ./assets/
Enable embeddable WebChat widget	greentic.cap.webchat.embed.v1	Generates embed HTML snippets (fullpage link, inline iframe, chat bubble) per tenant

Setting Capabilities in the Answers File

Instead of answering prompts interactively, set capabilities in the delegated bundle answers.capabilities array:

wizard-answers.json

{
  "wizard_id": "greentic-dev.wizard.launcher.main",
  "schema_id": "greentic-dev.launcher.main",
  "schema_version": "1.0.0",
  "locale": "en",
  "answers": {
    "selected_action": "bundle",
    "delegate_answer_document": {
      "wizard_id": "greentic-bundle.wizard.run",
      "schema_id": "greentic-bundle.wizard.answers",
      "schema_version": "1.0.0",
      "locale": "en",
      "answers": {
        "bundle_name": "My Digital Worker",
        "bundle_id": "my-digital-worker",
        "extension_providers": ["messaging-webchat"],
        "capabilities": [
          "greentic.cap.bundle_assets.read.v1",
          "greentic.cap.webchat.oauth.v1",
          "greentic.cap.webchat.i18n.v1",
          "greentic.cap.webchat.embed.v1"
        ]
      }
    }
  }
}

نصيحة

Capabilities are additive. Enabling greentic.cap.webchat.embed.v1 implicitly requires greentic.cap.bundle_assets.read.v1 because the embed snippets are written to the ./assets/ directory. The wizard handles this dependency automatically.

For full details on capabilities, scaffold behavior, and the overlay mechanism, see Bundle Assets.

Workflow

1. Create answers file

   Define your project configuration in a JSON AnswerDocument. Use gtc wizard --schema to fetch the current contract.

2. Run wizard

   gtc wizard validate --answers wizard-answers.json
   gtc wizard apply --answers wizard-answers.json --yes

3. Review generated files

   Check the generated bundle structure.

4. Configure extensions

   gtc setup ./my-digital-worker

5. Start runtime

   gtc start ./my-digital-worker

Customizing Generated Flows

The wizard generates basic flow templates. Customize them after generation:

apps/support-bot/flows/on_message.ygtc

name: on_message
version: "1.0"
description: Handle incoming messages

nodes:
  # Add your custom nodes here
  - id: analyze
    type: llm
    config:
      model: "gpt-4"
      prompt: "Analyze: {{message}}"
    to: respond

  - id: respond
    type: reply
    config:
      message: "{{analysis_result}}"

triggers:
  - type: message
    target: analyze

نصيحة

Use --dry-run first to preview the generated structure before committing to disk.

Component Scaffolding: http_client Capability

When scaffolding a new WASM component (for example via greentic-component new), the wizard can mark the component as needing outbound HTTP by setting http_client: true. This writes the capability declaration into the component manifest.

تنبيه

Desktop runner HTTP gate. Declaring http_client: true is a capability request — the runtime must grant it before the component can actually open outbound sockets. On the desktop runner profile, honouring this manifest flag has historically been a no-op: components that declared http_client: true had no wasi:http/outgoing-handler implementation linked, and runtime HTTP calls failed.

Starting with Greentic runner N.N.N (landing with the desktop HTTP gate fix, not yet released), the desktop profile will honour the manifest and grant wasi:http/outgoing-handler@0.2.0 automatically when a component declares http_client: true. Until that release is available, use the workaround below.

Workaround until the fix ships: ship your component with a custom WIT world that imports wasi:http/outgoing-handler@0.2.0 directly, rather than relying on the scaffolded manifest flag. Once you are on a runner that includes the desktop HTTP gate manifest-honouring fix, you can drop the custom world and use http_client: true as intended.

For components that emit Adaptive Cards via HTTP fetches (e.g. RAG lookups before returning an attachments[] array), see the WebChat extension’s Attachment Envelope Shape section for the expected component-output layout.

Troubleshooting

Invalid Answers File

Error: Failed to parse answers file

Ensure your JSON AnswerDocument is valid. Use gtc wizard --schema to confirm the required shape.

Missing Required Fields

Error: AnswerDocument answer `bundle_name` is required.

Check the required fields in gtc wizard --schema and update the JSON AnswerDocument.

Next Steps

• gtc setup - Configure extensions
• gtc start - Run the runtime
• Quick Start - Complete workflow