Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Use agentic scripts

Agentic scripts let you turn a small agentic procedure into a repeatable command-line workflow. They are useful when you want to use an LLM, caps, and agent loops in a non-interactive way, without starting a long-running agent.

Unlike toolang run or toolang start, an agentic script invokes one thunk directly, prints the final result to stdout, and exits.

This guide shows when to use agentic scripts, how to write them, and how to run them from the command line.

When to use them

Use agentic scripts when you want something more flexible than a shell script, but lighter than a running agent.

They work well for summarizing or rewriting local files, generating structured output, transforming notes or docs, reviewing content before committing it, or running short agentic procedures from Makefiles, GitHub Actions, and other automation tools.

Agentic scripts are best for non-interactive workflows. For interactive or long-running work, use chats, tasks, or chores instead.

Write a script

An agentic script is a normal Toolang program with one or more thunks. It can use caps from other packages, such as skills and services, and can also define inline caps in the same file.

#!/usr/bin/env toolang
 
# remote cap refs.
use psyche briceyan/concise
use skill briceyan/review
use service briceyan/github
 
# A inline prompt cap.
prompt project-style:
  Write clearly and directly.
  Prefer practical output over long explanations.
 
# Message input plus named parameters.
thunk rewrite(input: Message, tone: Text, audience?: Text):
  Rewrite the input for the requested tone and audience.
  Follow project-style.
 
# Named parameters only.
thunk slug(title: Text) -> Text:
  Convert the title into a lowercase URL slug.
 
# No input and no parameters.
thunk status:
  Explain what this script can do.
 
# Shorthand for message input.
thunk summarize(_):
  Summarize the input in three bullets.
  Follow project-style.

A thunk can accept message input, named parameters, both, or neither.

Use Message when the thunk accepts free-form text or file input from the command line. The shorthand _ can be used when the thunk only needs message input.

Named parameters are declared in the thunk signature, such as tone?: Text, audience?: Text, or title: Text. Optional parameters use ?.

A thunk with no input and no parameters can be used for simple commands such as status.

If you omit the thunk name, the thunk is callable as main. This is useful for small scripts that expose one primary operation.

Run the script

Run a Toolang script by passing the script path, the thunk name, and any parameters or input required by the thunk signature.

# Pass a file as message input.
toolang ./scripts/docs.too summarize @README.md
 
# Pass message input plus named parameters.
toolang ./scripts/docs.too rewrite tone=casual audience=developers "Make this clearer."
 
# Pass named parameters only.
toolang ./scripts/docs.too slug title="Use agentic scripts"
 
# Run a thunk with no input.
toolang ./scripts/docs.too status

Plain command arguments become text input. Values that start with @ are treated as file paths. too is an alias for toolang, so the same commands can also start with too.

If the script starts with a shebang, you can make it executable and run it directly.

chmod +x ./scripts/docs.too
 
# Run the script like a normal command-line executable.
./scripts/docs.too summarize @README.md

Inspect usage

Run a script file without a thunk name to print its usage and available thunks.

# These commands are equivalent.
toolang ./scripts/docs.too
toolang ./scripts/docs.too --help

This is convenient when a script exposes multiple thunks, or when you want to check the expected parameters before invoking one, without opening the source file.

© 2026 Toolang