Quick start - Buttons

Install

curl -fsSL https://raw.githubusercontent.com/autonoco/buttons/main/install.sh | sh

Or see installation for Docker, Go, and other options.

Initialize a project

Create a project-local .buttons/ directory so the button belongs to this workspace instead of your global ~/.buttons/ folder:

mkdir buttons-demo
cd buttons-demo
buttons init --agent agents-md

buttons init also writes .buttons/AGENTS.md and adds a Buttons section to AGENTS.md so coding agents know to discover and press existing buttons before writing one-off commands.

Create a button

Create an HTTP button that fetches weather data:

buttons create weather \
  --url 'https://wttr.in/{{city}}?format=j1' \
  --arg city:string:required \
  -d "Get current weather for a city"

Press it

buttons press weather --arg city=Miami

The button calls the API, substitutes city into the URL template, and prints the response.

See the result

buttons press weather --arg city=Miami --json

{
  "ok": true,
  "data": {
    "status": "ok",
    "stdout": "{\"current_condition\": [...]}",
    "button": "weather"
  }
}

Every command supports --json for structured output. Piped output auto-detects non-TTY and switches to JSON automatically.

View history

buttons history weather

Every press is recorded as a JSON file in the button’s pressed/ folder.

What to try next

Code buttons

Run inline shell, Python, or Node scripts.

Prompt buttons

Attach instructions for the consuming agent.

Workflows

Chain buttons into drawers.

Arguments

Typed args with validation.

CLI reference

Full flag reference for create.