> ## 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.

# Buttons

> The core unit of reusable work in Buttons.

A button is one reusable action with typed inputs, a runtime, structured output, and run history.

Use a button when an agent or human should be able to repeat the same action without rebuilding the command from scratch.

```bash theme={null}
buttons create deploy --arg env:string:required --code './deploy "$BUTTONS_ARG_ENV"'
buttons press deploy --arg env=staging
```

## Mental model

Each button owns:

| Part | Purpose |
| - | - |
| `button.json` | Name, args, runtime, timeout, metadata, and install fields. |
| `main.*` | Optional executable code for shell, Python, or Node buttons. |
| `AGENTS.md` | Agent instructions and context for when to use the button. |
| `pressed/` | Per-machine run history. |

Buttons live under `.buttons/buttons/<name>/` for a project or `~/.buttons/buttons/<name>/` globally.

## When to create a button

Create a button when the action is:

* repeated more than once
* risky to type by hand
* useful to an agent
* part of a larger workflow
* worth giving typed arguments and JSON output

## Related

* [Code buttons](/buttons/code)
* [HTTP API buttons](/buttons/http-api)
* [Prompt buttons](/buttons/prompt)
* [button.json](/concepts/button-json)
* [Drawers](/concepts/drawers)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.