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.

​
2026-04-12
Scaffold-by-default and simpler button creation

​
Scaffold-by-default and simpler button creation

Running buttons create without a source flag now scaffolds a placeholder script you can edit, instead of returning an error. This makes the default workflow scaffold → edit → press, which is faster for agents and humans alike.

​
New features

  • Scaffold-by-default — buttons create deploy --arg env:string:required now succeeds and writes a main.sh with a shebang and a TODO placeholder. Open the file, add your logic, and press. No --code or --file required. See code buttons.
  • Python and Node scaffolds — pass --runtime python or --runtime node to scaffold main.py or main.js with the correct shebang. Previously --runtime required --code.
  • Create output shows the file path — after buttons create, the CLI now prints the path to the scaffolded script and the press command, so you know exactly where to edit and how to run it. JSON output adds code_path and button_dir fields.

​
Updates

  • --code-stdin removed — the --code-stdin flag has been dropped. Anything it could do, --file or --code "$(cat)" can do with fewer flags to learn. If you were piping scripts via stdin, use --file instead.
  • --code repositioned as a shortcut — --code is now documented as a convenience for one-liners. The default path is to scaffold and edit.
​
2026-04-12
Prompt buttons, consolidated docs, and five upcoming button types

​
Prompt buttons, consolidated docs, and five upcoming button types

This release renames agent buttons to prompt buttons, simplifies the button type lineup, and previews five new button types on the roadmap.

​
New features

  • Five upcoming button types — the docs now include preview pages for button types coming soon: CLI, SQL, Webhook, Cron, and MCP. Each page explains the planned behavior and what it’s blocked on.

​
Updates

  • --agent renamed to --prompt — the --agent flag on buttons create is now --prompt. The JSON output field changes from agent_prompt to prompt. Existing buttons created with --agent will need to be recreated. See prompt buttons.
  • File buttons merged into code buttons — file-based button creation (--file) is now documented alongside inline code under code buttons. The separate file buttons page has been removed. No CLI changes — --file works exactly the same way.
  • API buttons renamed — “HTTP API buttons” are now just “API buttons” in the docs. The flags and behavior are unchanged. See API buttons.
  • Schema version bumped to v2 — newly created buttons use schema version 2. This reflects the --agent → --prompt rename in the stored spec.
​
2026-04-12
Four button types, drawers, and batteries

​
Four button types, drawers, and batteries

Buttons ships with four ways to create a button and two new command groups for organizing and running them.

​
New features

  • Code buttons — write inline shell, Python, or Node scripts directly in a button. Arguments are injected as BUTTONS_ARG_<NAME> environment variables to prevent shell injection. Supports --code for inline scripts and --code-stdin for piping longer scripts. See code buttons.
  • HTTP API buttons — wrap any HTTP endpoint as a pressable button with --url, --method, --header, and --body. Placeholders like {{arg}} are automatically encoded based on context (path segment, query string, JSON body, or form body) so values are always safe. See HTTP API buttons.
  • File buttons — import an existing script file with --file. The script is copied into the button folder at create time so the button is self-contained. No size limit applies, unlike inline code buttons. See file buttons.
  • Agent buttons — attach an LLM prompt to a button with --agent. Use it standalone to encode a task for an AI agent, or combine it with a code or HTTP button so the agent receives both the execution result and instructions in one response. See agent buttons.
  • Drawers — group related buttons into named collections with buttons drawer create and buttons drawer add. Use drawers to organize buttons by project, team, or workflow. See the CLI reference.
  • buttons smash — run multiple buttons in parallel with a single command. Useful for kicking off several tasks at once without scripting. See the CLI reference.
  • Batteries — manage environment variables and secrets with buttons batteries set, buttons batteries list, and buttons batteries rm. Values set here are available to all buttons at press time. See the CLI reference.

​
Updates

  • Release pipeline fix — resolved an issue where automated releases could fail on merge to main. Releases now run reliably on every push.
​
2026-04-12
Project-scoped buttons

​
Project-scoped buttons with buttons init

You can now scope buttons to a project instead of storing everything globally in ~/.buttons/.

​
New features

  • buttons init command — run buttons init in any project directory to create a local .buttons/ folder. Buttons created inside that project are versioned alongside your code and shared with collaborators via git. See folder structure for details.
  • Automatic discovery — all Buttons commands now walk up the directory tree to find the nearest .buttons/ folder, the same way git finds .git/. No flags or config needed — just cd into your project and go.
  • Discovery priority — Buttons resolves the home directory in order: BUTTONS_HOME environment variable first, then a .buttons/ folder in the current or any parent directory, then the global ~/.buttons/ fallback.
  • Git-friendly defaults — buttons init generates a .gitignore inside .buttons/ that excludes run history (pressed/) but keeps button specs, scripts, and agent instructions committed.
​
2026-04-12
v0.1.0 — Initial release

​
Buttons is live

buttons update command. You can now update Buttons to the latest version directly from the CLI. It downloads the correct binary for your OS, verifies the SHA256 checksum, and atomically replaces the running binary. Use --check to see if an update is available without installing. See the CLI reference for details.Agent skill discovery. AI tools like Claude Code, Cursor, and VS Code can now discover and install the Buttons skill automatically. Run npx skills add https://buttons.mintlify.app to teach your agent every command, flag, and output format. Learn more in the skill.md guide.MCP server and llms.txt. Buttons documentation is now searchable from AI tools via a hosted MCP server. Connect it in Claude, Cursor, or VS Code to search docs and retrieve full pages without leaving your editor. An auto-generated llms.txt index is also available for RAG pipelines and generative search engines.

​
Updates

Automatic releases. Every merge to main now triggers a new release with pre-built binaries and a Docker image on GitHub Container Registry. You no longer need to wait for a manual release to get the latest changes.

​
Bug fixes

Release pipeline fixed. An issue prevented pre-built binaries from being published for several early versions. This has been resolved — all new releases now correctly publish binaries for macOS, Linux, and Docker.