FAQ
Will switching package managers break my buttons?
Section titled “Will switching package managers break my buttons?”No. Script buttons are references, not copies. If you switch from npm to pnpm (for example by adding a pnpm-lock.yaml), the next scan recomputes every command. npm run dev becomes pnpm dev automatically. See package-manager detection.
Why does a button show “not found”?
Section titled “Why does a button show “not found”?”A script button becomes “not found” when its script can no longer be found in the scan. This usually happens when the script was renamed or deleted, its file type was disabled, or its directory is outside the scan scope. Run Rescan to refresh. See Troubleshooting.
Why did my nested package scripts disappear after 2.0?
Section titled “Why did my nested package scripts disappear after 2.0?”They didn’t. The scan scope changed. Buttons 2.0 scans the project root’s top level plus the directories you add, instead of the whole workspace recursively. Add your package roots as recursive scan directories in the Scan directories card (or buttons.scanDirectories) and the buttons recover on the next scan. Existing entries are kept and marked not found in the meantime. Nothing is deleted. See Monorepos.
Can Buttons run .sh or Python files?
Section titled “Can Buttons run .sh or Python files?”Yes. .sh files run as bash <file> and Python entry files (app.py, main.py, manage.py, run.py, server.py) run as python <file>, with the terminal’s working directory set to the file’s directory. Both are enabled by default via buttons.scriptFiles, and a detected venv/ or .venv/ gets Activate venv, Deactivate, and Install requirements buttons. See Script scanning.
Does Buttons scan Rust or Go projects?
Section titled “Does Buttons scan Rust or Go projects?”Yes. A Cargo.toml offers cargo build, cargo test, and cargo run. A go.mod offers go build, go test, and go run . from the module directory. Both types are enabled by default. Extra cargo or go tasks (clippy, fmt, a specific package) are custom commands.
I disabled a file type in settings. Why are its buttons still there?
Section titled “I disabled a file type in settings. Why are its buttons still there?”Disabling a file type in buttons.scriptFiles stops offering its scripts in the Project scripts tab, but it does not remove buttons already in your .buttons.json. Uncheck or remove those buttons manually if you no longer want them. This is intentional so a Rescan never wipes out your custom commands or selections.
Where are my buttons stored?
Section titled “Where are my buttons stored?”In two JSON files:
<workspace root>/.buttons.json: project buttons.~/.buttons.json: global buttons (applies to every project).
See .buttons.json.
What are global buttons?
Section titled “What are global buttons?”~/.buttons.json holds commands you want available in every project, so your go-to commands follow you across workspaces. The file is personal and is never shared with a project.
Do I have to create the buttons file myself?
Section titled “Do I have to create the buttons file myself?”No. Click Generate in the Project scripts tab and Buttons creates <workspace root>/.buttons.json for you, including every root-level discovered script. Opening a project never writes a file on its own.
Can I add a command that isn’t in a script file?
Section titled “Can I add a command that isn’t in a script file?”Yes. Use + Add command to add any literal command, for example docker ps. This is also how you run things from ecosystems Buttons doesn’t parse. See Custom commands.
How is the package manager detected?
Section titled “How is the package manager detected?”From the root lockfiles, in order: pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb → bun, package-lock.json → npm, defaulting to npm. See package-manager detection.
Why does my command open in a subfolder?
Section titled “Why does my command open in a subfolder?”For monorepo scripts, the terminal’s working directory is set to the script’s packageDir, so the command runs in the right place (for example packages/api). See Monorepos.
What’s the difference between Generate and Rescan?
Section titled “What’s the difference between Generate and Rescan?”Generate writes every root-level script into .buttons.json (and later adds any that are missing). Custom commands, notes, variants, and extra opted-in scripts stay. Rescan updates the existing file in place, preserving your inclusions and notes, marking missing scripts, and leaving new scripts unchecked. See Generate vs Rescan.
What’s the difference between Run, New Terminal, and System?
Section titled “What’s the difference between Run, New Terminal, and System?”Run executes in the current integrated terminal (or a dedicated Buttons terminal). New Terminal always opens a fresh integrated terminal and runs immediately. System opens your configured OS terminal at the project root, with the command already on the prompt, and does not run it. Press Enter there when you are ready. System ignores the script’s package directory on purpose: the outside terminal starts at the workspace root so you can edit the line first.
How do I give an AI the .buttons.json schema?
Section titled “How do I give an AI the .buttons.json schema?”Click the markdown icon in the sidebar or editor header. Copy the skill, or add BUTTONS-SKILL.md to the project root. See Using Buttons.