Button docs
Getting started with Button
You wrote a script, and you're tired of running it for your colleagues. By the end of this page that script has a web form your colleagues can fill in, run and download results from, while the job still runs on your computer. Any program you can start from a command line works: Python, Node, R, PowerShell, shell scripts and compiled binaries. Free covers 1 tool and 3 people.
1. Sign in to the app
Open the Button app and sign in with Google or a one-time email code. Google and an email code for the same address give you the same account.
2. Install the runner
The runner is the small program that runs your tools on your computer. Install it on the computer that has your script; every plan connects one computer per workspace.
The app shows the install command with your pairing code filled in. Copy it from the app and run it in a terminal.
On macOS or Linux:
curl -fsSL https://button.bitgate.dev/install.sh | sh -s -- --code <PAIR_CODE>
On Windows, in PowerShell:
$env:BUTTON_CODE="<PAIR_CODE>"; irm https://button.bitgate.dev/install.ps1 | iex
The pairing code works once and is valid for 10 minutes; if it runs out, get a new one in the app. To upgrade the runner later, run the same command without the code. The runner keeps running in the background as your user and starts again when you sign in to your computer. To move Button to another computer later, pair the new one; it replaces the old one.
3. Describe the tool
With a pairing code, the installer pairs your computer, starts the runner in the background and opens the runner's setup page in your browser. The page runs on your own computer (127.0.0.1) through a one-time link and closes after you publish or after 15 idle minutes. To open it again, run button-runner setup.
Pick the program to run, then add the inputs your form should ask for:
| Input | What your program receives |
|---|---|
| Text | The text, as one argument |
| Number | The number, as one argument |
| Yes/no | true or false |
| Choice | The option that was picked |
| File | The path to a copy of the uploaded file (one file per file field) |
Files can be up to 25 MB each, with up to 8 files and 100 MB per run.
Each value reaches your program as its own command-line argument, with no shell in between, and values can't start with -. That keeps the form from changing your command. It also means a number field can't take a negative number.
For results, have your script write files into the output folder: Button passes the folder's path to your program as an argument, wherever you put it in the command. In the setup page you also declare which result files to collect, as file patterns such as *.pdf. When the program exits with code 0, the files it wrote there that match those patterns become downloads on the tool page.
When you approve the tool, the runner pins the exact command and the form by a hash and will run nothing else for it. The security page explains what that does and doesn't cover.
4. Publish and invite colleagues
Publish the tool to give it its own page on Button, then invite colleagues by email. They open the link from the invite, sign in with Google or a one-time email code using the address the invite went to, fill in the form, press Run and download the results. They don't install anything, and they never pay. Send them this page if they want to know what to expect.
You can run your own tools too; those runs count toward your monthly runs. Every run is recorded with who started it and when, and you can revoke access or set it to expire at any time. If you change a tool's command or form later, it has to be approved again on your computer, and colleagues confirm the new version before running it.
5. Keep the computer on
Jobs run on your computer, not on our servers; our servers only pass the form values and files between the browser and your computer. So the computer has to be on and online, and the runner runs while you're signed in to it. On a Linux machine you log out of, run sudo loginctl enable-linger $USER once so the runner keeps going.
Tool pages show your computer's status: Ready, Busy or Offline. The runner runs one job at a time, for up to 30 minutes each. Nothing is queued: a run started while the computer is Busy or Offline is turned away, and your colleague tries again when it shows Ready.
Next
Last updated