Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt

Use this file to discover all available pages before exploring further.

Arguments let a button accept input. You declare them at create time with a name, type, and whether they are required or optional. At press time you supply values with --arg.

​
Declaring arguments

Pass --arg once per argument during buttons create: 
buttons create send-alert \
  --url 'https://hooks.example.com/alert' \
  --method POST \
  --body '{"channel": "{{channel}}", "message": "{{message}}", "urgent": {{urgent}}' \
  --arg channel:string:required \
  --arg message:string:required \
  --arg urgent:bool:optional \
  -d "Send a Slack-style alert"
The format is name:type:required or name:type:optional.

​
Supported types

TypeAccepted values
stringAny text
intInteger (e.g. 42, -7)
booltrue or false
Buttons validates types at press time and returns a VALIDATION_ERROR if the value does not match.

​
Passing values at press time

Use --arg key=value for each argument: 
buttons press send-alert \
  --arg channel=ops \
  --arg message="Deployment finished" \
  --arg urgent=true
Pass multiple values by repeating --arg: 
buttons press send-alert --arg channel=ops --arg message="Done"

​
Required vs optional

Required arguments cause a MISSING_ARG error if omitted. Optional arguments are silently absent — the button must handle their absence gracefully. 
buttons press send-alert --arg channel=ops
# error: missing required argument: message

{
  "ok": false,
  "error": {
    "code": "MISSING_ARG",
    "message": "missing required argument: message"
  }
}

​
How arguments reach code buttons

For code buttons and file buttons, each argument is injected as an environment variable named BUTTONS_ARG_<NAME> where <NAME> is the argument name uppercased: 
# Declared as:  --arg region:string:required
# In your script:
echo "Deploying to $BUTTONS_ARG_REGION"
Values are never interpolated directly into the script body. This prevents shell injection regardless of what string is passed.

​
How arguments reach HTTP buttons

For HTTP buttons, argument values are substituted into {{name}} placeholders in the URL, headers, and body. The substitution is context-aware — path segments, query parameters, JSON bodies, and form bodies each encode values differently. See URL and body templates for details.