First Touba Program

This walkthrough shows a minimal Touba program with show and ask.

The terminal commands assume the Touba CLI is available. If you only installed the VS Code extension through a VSIX file, use Touba: Run Current File to execute a simple .tb file from the editor.

1. Create the Source File

Create a file named hello.tb:

hello.tb

module examples.hello

strategy RunInteraction
    gives Text
    do
        show
            with message as "Touba ready"

        ask
            with prompt as "Search query?"
            into query

        show
            with message as "Query captured"

        give query

This program:

• displays a first message;
• asks the host for input;
• displays a second message;
• returns the received value.

give is a terminal return. Put show statements before give, then keep one give per execution path.

In a Touba project, the same module follows this path convention:

Project path

src/examples/hello.tb

A program with no tool declaration does not need a manifest or handler.

2. Compile to AIR

Terminal

touba compile hello.tb --out hello.air.json

Transformation:

Output

hello.tb -> AIR JSON

AIR describes executable nodes. It does not contain the user response.

3. Run and answer

Terminal input

touba run hello.air.json --interactive-user-inputs

The CLI displays “Search query?”. Enter parks and confirm: the program displays “Query captured” and returns your answer. In VS Code, Touba: Run Current File opens an input box for each ask.

Choose the input mode

Mode	Command	Use
Interactive	touba run hello.air.json --interactive-user-inputs	Answer in the terminal
Automated	touba run hello.air.json --user-inputs user-inputs.json	Supply answers from a file
Host-driven	touba run hello.air.json	Stop at the input request for the application to handle it

Supply answers from a file

Answers from a file

touba run hello.air.json --user-inputs user-inputs.json

The user-inputs.json file maps the interaction reference to the answer. You create it manually: each key is an interaction_ref from the compiled AIR, visible in a user_interaction_requested trace event.

For hello.tb, the ask reference is:

user-inputs.json

{
  "interaction:graph:strategy:examples.hello/RunInteraction:node:graph:strategy:examples.hello/RunInteraction:2": "parks"
}

Execution completes without interactive input.

To print the returned value:

Terminal

touba run hello.air.json \
  --user-inputs user-inputs.json \
  --output result

4. Generate the Trace

--output controls terminal output. To write the trace to a file, use --trace-out:

Terminal

touba run hello.air.json \
  --user-inputs user-inputs.json \
  --trace-out trace-success.json

This creates trace-success.json in the current directory.

5. Inspect the Trace

Terminal

touba inspect trace-success.json

Inspection gives a textual reading of events: start, display, pause, resume and completion.

Key Point

show and ask are host interactions. They are allowed in workflows, but not in function, because a Touba function stays pure and portable.