Button manifest reference: how a tool describes its command, form inputs, files and outputs for the runner

A manifest describes one tool: the program to run, how form values become its arguments, the form itself, the files it returns and its limits. The setup page (button-runner setup) writes it for you. This page describes the format, for when you write or review one by hand.

The approve step

The runner only runs a manifest that was approved on that computer. Publishing from the setup page approves it for you. A manifest published any other way needs:

button-runner approve manifest.json

The approval is pinned to a hash of the whole manifest: program, arguments, working folder, environment, form, outputs and limits. Any change makes a new manifest that needs a new approval, and people confirm the new version before they run it.

The approval doesn't cover what's inside your script. Edits to the script file take effect on the next run, without a new approval.

Without an approval, runs end with "The runner didn't respond in time" and nothing runs.

Example

{
  "manifest_version": 0,
  "executable": "/usr/bin/python3",
  "argv": [
    { "kind": "literal", "value": "/Users/sam/tools/clean.py" },
    { "kind": "literal", "value": "--month" },
    { "kind": "field", "field": "month" },
    { "kind": "input_file", "field": "export" },
    { "kind": "output_dir" }
  ],
  "cwd": "/Users/sam/tools",
  "env": { "REPORT_LOCALE": "en_US" },
  "fields": [
    {
      "name": "month",
      "label": "Month",
      "kind": "choice",
      "required": true,
      "options": ["January", "February", "March"]
    },
    {
      "name": "export",
      "label": "Bank export",
      "kind": "file",
      "required": true,
      "max_bytes": 26214400,
      "accept": [".csv"]
    }
  ],
  "outputs": [{ "name": "cleaned", "glob": "*.csv", "required": true }],
  "limits": { "wall_timeout_sec": 600, "max_output_bytes": 104857600, "max_log_bytes": 1048576 },
  "capture_raw_logs": false
}

When someone picks March and uploads march.csv, the runner runs this, in /Users/sam/tools:

/usr/bin/python3 /Users/sam/tools/clean.py --month March <run folder>/in/export/march.csv <run folder>/out

and returns every .csv file the script wrote to <run folder>/out.

Top level

Key	Rules
`manifest_version`	Always `0`
`executable`	The program to run, up to 512 characters. Use the full path; a bare name such as `python3` is looked up on the runner's `PATH`
`argv`	1 to 64 argument slots, see below. The program itself is not one of them
`cwd`	The folder the program runs in, up to 1024 characters. It has to exist
`env`	Up to 32 extra environment variables. Names are letters, digits and `_`, not starting with a digit. Values up to 1024 characters
`fields`	1 to 32 form fields, at most 8 of them files
`outputs`	Up to 8 result definitions
`limits`	Time and size limits, see below
`capture_raw_logs`	Optional, `true` or `false`. When `true`, the program's console output is kept with the run (up to `max_log_bytes`). Otherwise it's discarded

Argument slots

Each slot becomes exactly one argument.

Slot	Becomes
`{ "kind": "literal", "value": "--verbose" }`	That exact text. Not empty, up to 1024 characters
`{ "kind": "field", "field": "month" }`	The value entered in that field. Not for file fields
`{ "kind": "input_file", "field": "export" }`	The full path of the uploaded file. Only for file fields
`{ "kind": "output_dir" }`	The full path of an empty folder for results. At most one, and required when `outputs` isn't empty

There's no shell. Quotes, spaces, *, $VAR, | and > reach your program as plain text. A value that starts with - is refused, so nobody can slip in an extra option. Numbers arrive as written, such as 3 or 2.5, and yes/no fields as true or false.

If a field slot points at an optional field that has no default, a run where that field is left empty fails before the program starts. Give such fields a default, or leave them out of the command.

Form fields

Every field has:

Key	Rules
`name`	Lowercase letters, digits and `_`, starting with a letter, up to 64 characters, unique in the tool
`label`	What the form shows, up to 120 characters
`kind`	`string`, `number`, `boolean`, `choice` or `file`
`required`	`true` or `false`
`help`	Optional hint under the field, up to 500 characters

And per kind:

Kind	Keys
`string`	`max_len` from 1 to 100000 (required). Optional `default`, and `pattern`: a regular expression of up to 500 characters that the whole value must match
`number`	Optional `min`, `max` and `default`
`boolean`	Optional `default`
`choice`	`options`: 1 to 64 different values of up to 200 characters (required). Optional `default`, which must be one of the options
`file`	`max_bytes` from 1 to 26214400, which is 25 MB (required). Optional `accept`: up to 16 file types such as `.csv`

A file field takes exactly one file. For batches, ask for a ZIP and unpack it in your script.

Outputs

Key	Rules
`name`	The result's name, up to 64 characters
`glob`	Which files in the output folder to return, such as `report.pdf` or `.csv`, up to 256 characters. No `..` and no leading `/`. `` doesn't look into subfolders
`required`	When `true`, a run that writes no matching file fails

Your program writes its results into the folder it gets from the output_dir slot. Only regular files are returned, and a link that points outside the folder fails the run.

Limits

Key	Range
`wall_timeout_sec`	Whole seconds from 1 to 1800 (30 minutes). The program is stopped when time runs out
`max_output_bytes`	1 to 104857600 (100 MB): the total size of the returned files
`max_log_bytes`	0 to 1048576 (1 MB) of console output kept per run, when `capture_raw_logs` is on

A run carries up to 8 files and 100 MB. Inputs are deleted 24 hours after a run ends, outputs after 7 days. A computer runs one job at a time.

Tool manifest reference