Skip to content
LogoLogo

Run agentic scripts

A .too file exposes its agics and flows as commands. Invoke a runnable, inspect its progress, and save its result without opening a Chat session or starting an agent server.

Write a script

Save this as helpers.too:

#!/usr/bin/env toolang
 
## Rewrite text for an audience
agic rewrite(_, tone: Text, audience?: Text) -> Text:
    instruct:
        Rewrite the input in a {{tone}} tone.
        {% if audience %}Write for {{audience}}.{% endif %}
    user: {{_}}
 
## Generate a URL slug
agic slug(title: Text) -> Text:
    user: Convert {{title}} into a lowercase URL slug. Return only the slug.
 
## Describe this script
agic about() -> Text:
    user: Explain what text rewriting, URL slugs, and summaries are useful for.
 
## Summarize and polish text
flow summarize(_) -> Text:
    run -> Text:
        Summarize {{_}} in three bullets.
    run -> Text:
        Make these bullets clear and concise, preserving their meaning: {{_}}

A runnable's signature declares its inputs and output:

  • _ is the primary input; its default type is Part[], which can carry text and other model-visible content.
  • Named inputs use name: Type. Without a type, a named input defaults to Text.
  • ? makes an input optional.
  • () declares no inputs. Omitting the entire parameter list instead declares a primary input of type Part[].
  • -> Text declares the output type. The default output type is Part[].

An unnamed agic or flow is named default. Agics and flows share the generated command list. Use {{_}} and named placeholders to include inputs in messages; see coding conventions for more examples.

Inspect the generated CLI

toolang helpers.too --help
toolang helpers.too rewrite --help

The file's help lists its runnables. Runnable help shows its named and primary inputs, including which ones are required. ## documentation above a runnable provides its command description.

Supply inputs

Use NAME=VALUE for named inputs and -- before primary input:

toolang helpers.too rewrite tone=casual audience=developers -- Make this clearer.
toolang helpers.too slug title="Run agentic scripts"
toolang helpers.too about

Primary input can include file references:

toolang helpers.too summarize -- @README.md

Use - to read primary input from stdin. When stdin is piped or redirected, you can omit -:

cat README.md | toolang helpers.too summarize -
cat README.md | toolang helpers.too summarize

too is an alias for toolang. The shebang also lets you invoke the file directly:

chmod +x helpers.too
./helpers.too summarize -- @README.md

Save the result

Normal execution displays progress and a formatted result. Use --out (or -o) to save the final result, and -q to suppress progress:

toolang helpers.too summarize -q -o summary.txt -- @README.md
toolang helpers.too summarize -q -o - -- @README.md > summary.txt

-o - writes the result to stdout. Text-only results are saved as text; other content is saved as a JSON array of parts. The destination directory must exist.

Control a run

Choose a model, restrict resources, or set a budget before --:

toolang helpers.too summarize --model openai/gpt-5 --limit tokens=10000 -- @README.md
toolang helpers.too summarize --allow tools=none -- @README.md

Resource allowances are bounded by the agent's configuration and the runnable's directives. Use toolang helpers.too summarize --help for all execution options.

© 2026 Toolang