Code buttons - Buttons

A code button is a script the runtime executes every time you press it. The script lives as a file inside the button folder, so you can edit it the same way you edit any other file.

The default flow: scaffold, edit, press

The simplest way to create a button is to let Buttons scaffold a placeholder script you can fill in. Declare the args you’ll need up front — they’re part of the button spec and can’t be added later without recreating the button:

buttons create greet --arg name:string:required
# Created button: greet
#   Edit:  /Users/you/.buttons/buttons/greet/main.sh
#   Press: buttons press greet

Open the scaffolded main.sh — it has a shebang, a TODO comment, and a hint about where args arrive:

#!/bin/sh
set -eu

# TODO: add your command here
# Args arrive as $BUTTONS_ARG_<NAME>

Edit it to whatever you want:

#!/bin/sh
echo "Hello, $BUTTONS_ARG_NAME"

Press:

buttons press greet --arg name=Ada
# → Hello, Ada

Args are declared at create time and stored in button.json. If you need to change them, delete and recreate the button — your main.sh is at the same path each time, so you can copy your edits over.

Scaffold in Bash, Python, or Node

Pass --runtime to scaffold with the right shebang and extension:

buttons create deploy --runtime bash --arg env:string:required
# → scaffolds main.sh with:
#     #!/usr/bin/env bash
#     set -euo pipefail

buttons create parse-json --runtime python --arg input:string:required
# → scaffolds main.py with:
#     #!/usr/bin/env python3
#     # TODO: add your code here
#     # Args arrive as os.environ["BUTTONS_ARG_<NAME>"]

buttons create transform --runtime node --arg payload:string:required
# → scaffolds main.js

Flag value	Interpreter used	File written
`shell` (default)	`/bin/sh`	`main.sh`
`bash`	`bash` from `PATH`	`main.sh`
`python`	`python3`	`main.py`
`node`	`node`	`main.js`

The bash runtime requires Bash to be installed. If it is unavailable, buttons press returns RUNTIME_MISSING; Buttons does not install it automatically.

Shortcuts for when you already know the code

Three shortcuts let you skip the edit step when the script is trivial or already on disk.

`--code 'one-liner'`

Pass a one-line script inline. Useful when the body is a single command and quoting isn’t painful:

buttons create hostname --code 'hostname -f'
buttons create ls-home --code 'ls -la ~' --runtime shell

Inline code is capped at 64 KB. Beyond that, write it to a file and use --file.

`--file ./path/to/script.sh`

Copy an existing script into the button folder. The file is copied (not symlinked) so the button is self-contained:

buttons create deploy \
  --file ./scripts/deploy.sh \
  --arg env:string:required \
  --arg version:string:required \
  -d "Deploy a tagged release"

When importing code, Buttons infers the runtime from the file extension or shebang. Without a recognized extension or shebang, Buttons defaults to /bin/sh.

Argument injection

Arguments are never interpolated into the script body. They arrive as environment variables named BUTTONS_ARG_<NAME> (uppercased):

# Declared:  --arg bucket:string:required
# Available:
echo "$BUTTONS_ARG_BUCKET"           # shell
os.environ["BUTTONS_ARG_BUCKET"]     # python
process.env.BUTTONS_ARG_BUCKET       # node

This prevents shell injection regardless of what the caller passes at press time.

Reporting progress

Long-running buttons can stream progress while they run. Before executing your script, the engine sets $BUTTONS_PROGRESS_PATH to a per-press file. Append one JSON object per line (JSONL) to it, and buttons tail -f follows those events live in another terminal.

#!/bin/sh
set -eu

# $BUTTONS_PROGRESS_PATH is set by the engine on every press.
say() { printf '{"message":"%s"}\n' "$1" >> "$BUTTONS_PROGRESS_PATH"; }

say "cloning repo"
git clone "$BUTTONS_ARG_REPO" work
say "installing deps"
( cd work && npm install )
say "done"

Follow it while it runs:

buttons tail deploy -f

Progress events are advisory and separate from the result — the final structured output still goes to stdout when the press finishes. A script that never writes to $BUTTONS_PROGRESS_PATH simply produces no progress to follow. See the tail CLI reference.

Where the code lives

After buttons create, the button folder contains:

~/.buttons/buttons/<name>/
  button.json     # spec: args, runtime, timeout
  main.sh         # your code (or main.py / main.js)
  AGENTS.md       # notes for agents pressing this button
  pressed/        # run history, one JSON file per press

Edit main.sh any time. Changes take effect on the next press — no recreate needed.

Example: wrap a deploy script

# scripts/deploy.sh
#!/bin/bash
set -euo pipefail

ENV=$BUTTONS_ARG_ENV
VERSION=$BUTTONS_ARG_VERSION

echo "Deploying $VERSION to $ENV..."
kubectl set image deployment/app app=registry.example.com/app:$VERSION -n $ENV
kubectl rollout status deployment/app -n $ENV

Import it:

buttons create k8s-deploy \
  --file ./scripts/deploy.sh \
  --arg env:string:required \
  --arg version:string:required \
  -d "Roll out a new image version to a Kubernetes namespace"

Prompt buttons — attach an instruction to any button for the consuming agent
Arguments — declare and pass typed args
JSON output — capture results programmatically
Folder structure — what lives inside a button folder

​The default flow: scaffold, edit, press

​Scaffold in Bash, Python, or Node

​Shortcuts for when you already know the code

​--code 'one-liner'

​--file ./path/to/script.sh

​Argument injection

​Reporting progress

​Where the code lives

​Example: wrap a deploy script

​Related

The default flow: scaffold, edit, press

Scaffold in Bash, Python, or Node

Shortcuts for when you already know the code

`--code 'one-liner'`

`--file ./path/to/script.sh`

Argument injection

Reporting progress

Where the code lives

Example: wrap a deploy script

Related