Extend Bolt

Build a rich app in 5 minutes.

Copy a template, change data in one file, and get tiles, drill down with Back, a detail panel, a cache and plain error rows. You do not write code.

Copy, edit, check, pack, drop.

Terminal
# one time: get the template (a public repo; needs python3 and node 18 or newer)
git clone https://github.com/SparcleHQ/bolt-apps ~/bolt-apps
cp -R ~/bolt-apps/kit/examples/portal-template ~/my-app
cd ~/my-app

# 1. edit scripts/config.json and scripts/fixtures.json (the four things below),
#    rewrite check.json cases for your views and delete golden/ files no case names (golden_stale),
#    set "id" in bolt-app.json, and delete the old utilities/portal-template.yaml
#    (step 2 writes the new one)

# 2. build the app file from config.json (never edit the yaml by hand)
python3 scripts/engine.py --emit-yaml > utilities/<id>.yaml

# 3. check it on the sample data, review golden/ once, then check again
BA=~/bolt-apps/toolkit/bin/bolt-apps.mjs
node "$BA" check . --update-golden     # once, then read the golden/ files
node "$BA" check .

# 4. pack it for your own use (run node "$BA" keygen once before the first pack)
node "$BA" lint . --personal
node "$BA" pack . --personal --version 1.0.1 --out ../my-app-1.0.1.boltpack   # a higher version on every rebuild

# 5. drop my-app-1.0.1.boltpack on the Bolt launcher or Bolt Apps
  1. Copy the template. kit/examples/portal-template in the public bolt-apps repository. It runs as is, on sample data, with no key and no network.
  2. Change the four things below. Also set id in bolt-app.json to the new id (and title, summary), and rename utilities/<template>.yaml to utilities/<id>.yaml so the old one is gone.
  3. Emit the app file from config.json. Keep id the same in config.json, bolt-app.json, the yaml file name and the folder name (id_mismatch otherwise).
  4. Check. check runs the script on recorded data and tests every row against the row contract. It does not draw the rows: open the app in Bolt to see them.
  5. Pack and drop. pack --personal --version 1.0.1 --out ../my-app-1.0.1.boltpack writes the pack next to the folder. Keep packs outside the app folder. Raise the version (1.0.2, 1.0.3) every time you pack again: Bolt refuses a pack that is the same version or older than the one installed. Pack again with the same key you first used: a new keygen makes a different signer, and Bolt then refuses with "already belongs to". Drop it on the Bolt launcher or Bolt Apps (not Admin settings, which accepts only company-signed bundles). Bolt shows the permissions and asks you to confirm.
  6. Run it once in Bolt. Type =<chip>, press Enter on the app's run row if Bolt asks for your OK, and see the overview rows. The tools cannot draw the launcher, so this step is the proof. If Bolt says it cannot tell which files the app runs, see the rules Bolt enforces.

Pick your starting point.

Read kit/examples/index.json: for each template it gives the layout, the pane kinds, the techniques, the files to edit and the check command. Pick the closest one, copy its folder, and edit only the listed files.

TemplateWhat it teachesBacked byPanesEdit only
portal-templateoverview tiles, drill down to lists, detail with related rows, per-row detail panelany REST API with a keycards, entity_previewscripts/config.json, scripts/fixtures.json
acme-dashcompliance dashboard, 7 lists, controls drill to linked tasksfictional APIcards, entity_previewscripts/config.json, scripts/fixtures.json
widget-galleryWhich right-hand panes a personal app can draw and the exact `bind` keys each needssample datacards, chart, table, detail, json_tree, diff, entity_preview, markdownscripts/config.json, scripts/fixtures.json
form-templateA declarative input form (number, select, date, text with a length limit, toggle), checks on the values, a local log, and the log shown as a tablea local filetablescripts/config.json
chart-templateEvery chart the launcher can draw, each fed both ways, plus a cards-only dashboardany REST APIcards, chartscripts/config.json, scripts/fixtures.json
table-templateThe `table` pane: columns with `label`, `align`, `format` (text, number, percent, currency, date), `unit`, per-column `total` (sum, avg, min, max, count), `sort` and `totals_label`any REST APIcards, tablescripts/config.json, scripts/fixtures.json
lookup-templateOne typed word in, a stitched result outOpen-Meteo geocoding and forecast (keyless)cardsscripts/config.json, scripts/fixtures.json
file-insights-templateA local-file app: the person types the path of a CSV, the app reads it with the standard library only, finds the date, value and group columns by name, and shows totals, a titled line chart, a titled bar chart, a table and a list of things to watcha local CSV filecards, chart, table, markdownscripts/config.json, scripts/fixtures.json
cli-wrapper-templateHow to wrap a command-line tool as a Bolt App, using the system `ping` as the toolthe system ping commandcards, chart, markdownscripts/config.json
system-glanceThe command-probe archetype on the flat kit: three read-only probes (`df`, `uptime`, `lsof` or `ss`) run in parallel inside one deadline, each parsed on its owndf, uptime, lsof or sscardsscripts/system-glance.py
repo-radarJoining several remote APIs into one verdictGitHub REST; npm registry and downloads; OSV.dev; Hacker News searchcards, diff, detail, chart, tablescripts/config.json, scripts/fixtures.json
aroundStitching independent systems on coordinatesNominatim; Overpass; CityBikes; Open-Meteo; Wikipedia geosearchcards, detail, table, chartscripts/config.json, scripts/fixtures.json
local-service-template`runtime: http_local`: an app with no script at alla service on 127.0.0.1 (Ollama model list as the example)detailutilities/localmodels.yaml
widget-gallery-2The three panes `widget-gallery` has no room for, because a personal app may have at most 8 views including the overview and that gallery already uses all 8sample data (generated swatches)card, image_grid, cardsscripts/config.json, scripts/fixtures.json

The engine templates (portal-template, acme-dash, chart-template, lookup-template, table-template, widget-gallery, widget-gallery-2) make the app file with python3 scripts/engine.py --emit-yaml and you never edit engine.py. The others have their own script, and for those you are expected to edit it (the functions their README names), but never bolt_app_kit.py: around uses around.py, repo-radar radar.py, cli-wrapper-template wrap.py, file-insights-template insights.py; run that script with --emit-yaml as its README shows. system-glance has no --emit-yaml: edit utilities/glance.yaml and scripts/system-glance.py by hand. local-service-template has no script: edit its utilities/localmodels.yaml. Full reference: ENGINE.md.

MCP servers

A personal app has no direct way to call an MCP server. The workaround is a script that starts a command line tool or an MCP client, reads its output and prints rows. Name that script as {{scripts_dir}}/<file> like any other.

What backs your app.

BackingRuntimeHowStart fromLimits
CLI commandbridgea script runs the command as an argument list with no shellcli-wrapper-template (one tool with typed arguments), system-glance (parallel probes)personal pack only; per-OS command table; stderr is not seen; 60 s at most
remote HTTP APIbridgea script calls the API (urllib) inside a deadline; keys from keychain or ~/.config//.envrepo-radar, around (several APIs joined); lookup-template, chart-template, table-template, portal-template (one API, config only)declare network; a shell variable never reaches the script
local HTTP servicehttp_localBolt makes one GET or POST to 127.0.0.1, localhost or ::1; no scriptlocal-service-templateloopback only, one request, no secrets, no chaining
filebridgea script reads a path the person types, with caps and a regular-file checkfile-insights-template (read), form-template (write its own log)declare files; the path travels as query words, not in a nav arg
MCP servernone nativea bridge script starts the MCP server over stdio and calls one tool (see ENGINE.md, MCP workaround)the snippet in ENGINE.mdtested only against a stand-in server; the person needs the server installed; 15 s cap; one tool per app

Typed words and nav args

A nav arg is one plain token: no slash and no spaces. A typed path or owner/repo therefore cannot travel in a row's nav. The kit keeps the last typed query in its cache (~/.bolt-apps/cache/<app>) and the script repeats it. A personal app has at most 8 views including the overview. widget-gallery uses all 8, so the card pane, image grid and image cards are in widget-gallery-2.

Auth modes

ModeWhat the app does
No keySends nothing. Four of the five sources in around.
Optional keySends Authorization: Bearer ... when you add one, and works without it.
Required free keyWith no key the view shows an "Add your free key" row with the exact one-line setup command. The key goes in the query value the service names.
BearerAuthorization: Bearer ...
BasicAuthorization: Basic ... built from user and password. Only a masked form is ever shown.

Keys come from the keychain or the owner-only file, never a shell variable. Native sign-in flows are not covered by these examples.

Live terms of public APIs (checked 2026-11-15 with real requests)

SourceWhat to respect
GitHub api.github.com60 requests an hour without a token, 5,000 with one. A User-Agent is required: a request without one is refused.
Nominatim nominatim.openstreetmap.orgA User-Agent naming the app (none got HTTP 403) and at most 1 request a second. around waits 1.1 s between calls and keeps an answer 30 days.
Overpass overpass-api.dePublic and shared: it answers 502 or 504 when busy and a good call took 32 to 34 s. The app keeps places 1 hour and shows an old copy, so rows can say "Places down". That is real, not a bug.
Open-Meteo, CityBikes, WikipediaNo key. Open-Meteo allows 600 requests a minute and asks for credit; Wikipedia expects a descriptive User-Agent.

Pane kinds that work, and ones that do not.

KindShowsMain bind keys
entity_previewSelected row: tile above, label and value fields, chips, Markdown body, buttonstitle, subtitle, tiles_above, fields, body, actions
cardsAll rows as a grid, or as number tiles with a metertitle, subtitle, badge, footer, and for tiles layout: tiles, value, unit, max
tableAll rows as a table, with totalscolumns, sort, totals_label
detailLabel and value pairs for the selected rowtitle, subtitle, fields
chartA line, bar or sparklinetype, values or y with x, label, color, unit
card, markdown, json_tree, diff, image_gridOne card, a Markdown page, a JSON tree, two texts side by side, picturesSee the Agent guide table

Do not use these

KindWhat Bolt showsUse instead
imageThis app asks for an image pane, which cannot show app data. Use image_grid for pictures.image_grid (inline data images only)
color, weather, date, calcThis app asks for a <kind> pane, which cannot show app data. Use table, detail, cards or chart.table, detail, cards or chart
mapLoads, but shows the launcher's own map state, not your data (no bind keys)A row url that opens a maps page (Open in Maps)
entityRefused when the file loadsentity_preview

What a chart can and cannot do

Rule
Typesbind.type is line (the default), bar or sparkline. There is no pie, donut or area chart.
Data, one rowbind.values names a row field that holds a list of numbers.
Data, one point per rowbind.y names a number field; bind.x names the label field.
Colourbind.color is accent or muted. Nothing else.
HoverTooltips on points and bars only. No click or zoom.
Instead of a pie or donutNumber tiles with a meter (kpi_max) for a part of a whole, or a table with a percent column.

Where to store API keys and passwords.

The template reads a key with the kit's get_secret. It tries an environment variable first (useful only in a terminal and in tests, because Bolt never passes it), then the keychain, then the file. When none is found the app shows a row with the exact setup line.

PlaceRule
1. The system keychain (macOS security, Linux secret-tool)Encrypted, per user, never a file. Not available on Windows: use the file there. Needs the tool installed.
2. ~/.config/<app id>/.env, mode 0600, one NAME=value lineWorks everywhere. Plain text on disk, outside the app folder. The engine refuses it if others can read it.
A shell environment variableDoes not work under Bolt. Bolt starts the script with an empty environment except a short allowlist (HOME, PATH, USER, LANG, TERM, TMPDIR, TZ, LC_*, XDG_*, CA bundle variables) and never forwards secret-looking names, those containing TOKEN, KEY, SECRET, PASS, PWD, CRED, AUTH, PRIVATE, SESSION or COOKIE. It works only in a terminal and in tests.
An inputs field of type secretDo not use it for keys: how the value reaches the run log is not measured.
Set a key (Terminal)
# macOS (asks for the key)
security add-generic-password -s bolt-app-<app id> -a <NAME> -w
# Linux (asks for the key)
secret-tool store --label=<app id> service bolt-app-<app id> account <NAME>
# any system: the file, only you can read it
(umask 077; mkdir -p ~/.config/<app id> && printf '<NAME>=' >> ~/.config/<app id>/.env)
# then open that file and paste the key right after the = sign

Never put a key in

Never inWhy
The app file or config.jsonBoth are packed and shared.
fixtures.json, golden/, the READMESamples are public. Use made-up data.
A packA .boltpack is a file you may hand to others.
The cache, a row, a comment or a logThe engine never prints, caches or shows the key. Do not add a path that does.
A query wordIt is typed on screen and passed to the script on its command line, where other programs on the computer can read it.

Two cases, two rules.

Gallery appPersonal rich app
Tier1 or 2: text, search, transform3: runs a script and calls the network
Packbolt-apps pack, signed with your own keybolt-apps pack --personal, for you only. Never build a pack by hand.
InstallFrom the gallery, when it opensDrop the .boltpack on the Bolt launcher or Bolt Apps. Bolt shows the permissions and asks you to confirm.
CacheNo script, so noneInside the script: cache.ttl and cache.stale_max in config.json. Not the YAML field cache_ttl_seconds, which is the admin connector cache and is refused in a User App.

The files, all public.

FileLink
The template, a folder to copykit/examples/portal-template
Its config, the file you editscripts/config.json
Its engine, the file you do not editscripts/engine.py
A full example: 8 views, 3 levelskit/examples/acme-dash
The row contractkit/schema/row.schema.json
Rules for agentsAGENTS.md

The four things you change.

#WhereWhat
1config.json app, apiApp id, chip, title. base_url, the key variable name, the .env path, the auth header.
2config.json endpointsOne entry per API path, with map from your field names to the names the views use. Dotted paths work: "owner": "assignee.name".
3config.json stats, overview, viewsCounters, the tiles on the overview, and per view: row title, subtitle, tile, up to 5 detail fields, body, link, and children for a drill to a second list.
4scripts/fixtures.jsonA real response saved per endpoint. check uses it; the shipped app stays live (api.fixture_default is false).
scripts/config.json (the parts you change)
{
  "app": { "id": "my-app", "chip": "myapp", "title": "My app", "icon": "globe", "service": "My Service" },
  "api": {
    "base_url": "https://api.example.com",
    "key_env": "MY_API_KEY",
    "env_file": "~/.config/my-app/.env",
    "auth_header": "Authorization",
    "auth_prefix": "Bearer ",
    "fixture_default": false
  },
  "endpoints": {
    "tickets": { "path": "/v1/tickets",
                 "map": { "title": "summary", "status": "state", "assignee_name": "assignee.name" } }
  },
  "views": [
    { "id": "tickets", "title": "Tickets", "endpoint": "tickets",
      "item": { "title": "{title}", "subtitle": "{status|human} · {assignee_name}",
                "fields": [{ "label": "Status", "value": "{status|human}" }] } }
  ]
}

Put the key in the system keychain or the owner-only .env file: see Where to store API keys. A shell environment variable does not reach the app under Bolt. It is never printed, cached or put in a row.

The drill flow.

The app file takes view and arg from the words you type after the key (query.word(0), query.word(1)). Each Enter on a row with nav runs the script again with that view and arg. A detail view reuses an existing view, so it does not use up one of the 8.

Overview, list, detail
=my-app                      type the key, press Enter
   |
   v
OVERVIEW  (view "overview", one summary row per list)
   [ Summary           no nav, its tile shows on the right ]
   [ Tickets · 12      nav {view: tickets}                 ]  Enter
   [ Projects · 4      nav {view: projects}                ]  Enter
   [ Documentation     url                                 ]  Enter opens the page
   [ Refresh           nav {view: overview, arg: refresh}  ]  Enter fetches fresh data
   |
   v  Enter on "Projects"           launcher runs: engine.py projects -
LIST      (view "projects")
   [ Back              nav {back: true}      first row, always ]
   [ Website refresh   nav {view: projects, arg: P-1}          ]  Enter
   [ Billing cleanup   nav {view: projects, arg: P-3}          ]
   [ Refresh           nav {view: projects, arg: refresh}      ]
   |
   v  Enter on "Website refresh"    launcher runs: engine.py projects P-1
DETAIL    (same view, with an arg; its rows come from views[].children)
   [ Back              nav {back: true}                        ]
   [ Add SSO           pane: tickets  (drawn by the tickets panel) ]
   [ Dark mode colors  pane: tickets                           ]

Which config field gives which feature.

FeatureYou write (config.json)What reaches Bolt (row and app file)
Overview with tiles that drill into a listoverview.rows[] with view; the tile uses statsRow nav {view}, right panel cards with layout: tiles
Up to 8 viewsviews[], at most 7 besides the overviewpresentation.views, view_arg: view
Which view to showBuilt in: the first word you typeargs from query.word(0) and query.word(1)
Back row, first in every listBuilt inRow nav {back: true}
Level 3: a detail view that lists related rowsviews[].children (rows of another view whose match field equals this row's id). No new view needed.Row nav {view, arg} with the id as arg
Detail panel for the selected rowitem.fields (up to 5), item.body, item.tileRow pane, right panel entity_preview with tiles_above, fields, chips, body
Tile with a meter and a badgetile with label, value, max, unit, note, foot, badge rulesRow kpi_label, kpi_value, kpi_unit, kpi_max, kpi_note, kpi_foot, kpi_badge
Open and Copy buttonsitem.urlRow open_url and copy_text, yaml actions open and copy
A row that opens a web pageoverview.rows[].urlRow url
Filter by one wordBuilt in: =my-app tickets openargs from query.word(1). The row has no filter field.
Cache 45 s, old copy up to 24 hcache.ttl, cache.stale_maxRefresh row nav {view, arg: refresh}
Offline, rejected key, no key, partial loadBuilt in, one plain row eachA row with nav back to the same view, so Enter retries
Key stays privateapi.key_env, api.env_file (keychain first, then the file)Never in a row, the yaml or the cache
Tests with no key and no network"fixture": true in check.json (whole app, or one case; a case wins, false forces live) and scripts/fixtures.jsonA shipped app is live: api.fixture_default is false. An installed pack cannot be switched to sample data. In a terminal, BOLT_APP_FIXTURE=1 runs on samples.

Rendering rows.

The engine writes every row for you. You only need this section to understand what the launcher gets, or to write a script by hand. Each sample is a real row from kit/examples/acme-dash/golden with the empty fields left out. Next to it is the app file part that draws it, and the layout you see. Rows are one JSON array on stdout, at most 200. The full contract is row.schema.json.

1. A drillable row

A row with nav {view, arg} takes the person to another view when they press Enter. arg is optional. A nav row carries no actions of its own.

Row
{
  "title": "Tasks · 41 of 50 done",
  "subtitle": "7 in progress · 2 not started",
  "icon": "list",
  "nav": { "view": "tasks" },
  "kpi_label": "Tasks done", "kpi_value": 41, "kpi_max": 50,
  "kpi_note": "of applicable tasks", "kpi_foot": "7 in progress", "kpi_badge": "IN PROGRESS"
}
Row with an arg (a filter word here)
{
  "title": "Next up",
  "subtitle": "4 things to do",
  "icon": "list",
  "nav": { "view": "tasks", "arg": "urgent" }
}
App file: view and arg become the script's arguments
args:
  - { name: view, from: "query.word(0)", default: overview }
  - { name: arg, from: "query.word(1)", default: "-" }
bridge:
  command:
    macos: "python3 {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
    linux: "python3 {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
    windows: "python {{scripts_dir}}/engine.py {{view}} {{arg}} {{scripts_dir}}/config.json {{scripts_dir}}/fixtures.json {{scripts_dir}}/bolt_app_kit.py"
  parse: json
  timeout_seconds: 25
presentation:
  widget: list
  title_field: title
  subtitle_field: subtitle
  view_arg: view
  views:
    overview: {}
    tasks:
      right_widget: ...   # see pattern 4
Layout
Overview                                  | Right panel (tile of the selected row)
------------------------------------------+---------------------------------
> Tasks · 41 of 50 done                   |  Tasks done          IN PROGRESS
  7 in progress · 2 not started           |  41 / 50  [#########---]
  Next up                                 |  of applicable tasks
  4 things to do                          |  7 in progress
  Refresh                                 |
                                          |  Enter on a row with nav runs the
                                          |  script again with that view and arg

2. The Back row

The first row of every list and detail view is nav {back: true}. It needs no yaml of its own: the engine writes it. The app file only sets view_arg: view.

Row
{
  "title": "Back",
  "subtitle": "50 tasks",
  "icon": "arrow-left",
  "nav": { "back": true }
}
Layout
Tasks
------------------------------------------
> Back                       (always first)
  50 tasks
  Check endpoint protection status (EU)
  In progress · Elena R. · due 2026-07-15
  ...

3. Cache and refresh

Answers are cached for cache.ttl seconds. If the API fails and an old copy exists (up to cache.stale_max), the old rows show under a STALE row. A failure is never cached. A row whose nav points at the same view with arg: refresh skips the cache when you press Enter. For a detail view the arg is refresh.<id>.

config.json
"cache": { "ttl": 45, "stale_max": 86400 }
Rows (comments added here; real output is plain JSON)
// 1. the refresh row, last in every list (golden/overview.json)
{
  "title": "Refresh",
  "subtitle": "Enter to fetch fresh data",
  "icon": "RefreshCw",
  "nav": { "view": "overview", "arg": "refresh" },
  "pane": "overview"
}

// 2. the server is down but an old copy exists (golden/stale.json)
{
  "title": "Acme Compliance is not answering. Showing data from 3.0 h ago.",
  "subtitle": "Could not connect to Acme Compliance. Enter to retry",
  "icon": "AlertCircle",
  "nav": { "view": "tasks", "arg": "refresh" },
  "pane": "tasks",
  "kpi_label": "Data age", "kpi_value": 10800, "kpi_unit": "s",
  "kpi_note": "old copy", "kpi_badge": "STALE"
}

// 3. the data came from the cache (written by engine.py notice_rows;
//    shown once the copy is 2 s or more old; 12 s here as an example)
{
  "title": "Loaded from cache, 12 s old",
  "subtitle": "Enter to refresh (data is kept 45 s)",
  "icon": "RefreshCw",
  "nav": { "view": "tasks", "arg": "refresh" },
  "pane": "tasks",
  "kpi_label": "Data age", "kpi_value": 12, "kpi_unit": "s", "kpi_max": 45,
  "kpi_note": "from cache, Enter to refresh", "kpi_badge": "CACHED"
}
Layout
Tasks
------------------------------------------
  Back                       50 tasks
> Loaded from cache, 12 s old
  Enter to refresh (data is kept 45 s)      <- Enter runs: engine.py tasks refresh
  Check endpoint protection status (EU)        (skips the cache, fetches again)
  ...
  Refresh
  Enter to fetch fresh data

4. A detail panel per row

A row's pane names the view whose right panel draws it. The panel binds row fields: kpi_* into tiles_above, the fields f1 to f5 into fields (kind chips for a tag list), body as Markdown, and actions by id.

Row
{
  "title": "Asset inventory",
  "subtitle": "1 linked tasks · Portal · owner Sam K.",
  "icon": "Layers",
  "body": "## Asset inventory\n\nControl asset inventory.\n\nEnter lists the tasks linked to this control.",
  "nav": { "view": "controls", "arg": "C-017" },
  "pane": "controls",
  "kpi_label": "Linked tasks", "kpi_value": 1,
  "kpi_note": "tasks behind this control", "kpi_badge": "PORTAL",
  "open_url": "https://app.example.com/acme/controls/C-017",
  "f1": "SOC 2, ISO 27001", "f2": "Portal", "f3": "Sam K."
}
App file: presentation.views
views:
  overview: {}
  controls:
    right_widget:
      kind: entity_preview
      mode: selected_row
      bind:
        title: "{{row.title}}"
        subtitle: "{{row.subtitle}}"
        tiles_above:
          title: "{{row.kpi_label}}"
          value: "{{row.kpi_value}}"
          unit: "{{row.kpi_unit}}"
          max: "{{row.kpi_max}}"
          subtitle: "{{row.kpi_note}}"
          badge: "{{row.kpi_badge}}"
          footer: "{{row.kpi_foot}}"
        fields:
          - { label: "Frameworks", value: "{{row.f1}}", kind: chips }
          - { label: "Portal", value: "{{row.f2}}" }
          - { label: "Owner", value: "{{row.f3}}" }
        body: "{{row.body}}"
        actions: [open, copy]
Layout
Controls                                  | Asset inventory
------------------------------------------+---------------------------------
  Back                                    |  [tile] Linked tasks   PORTAL
> Asset inventory                         |         1  tasks behind this control
  1 linked tasks · Portal · owner Sam K.  |  Frameworks  [SOC 2] [ISO 27001]
  ...                                     |  Portal      Portal
                                          |  Owner       Sam K.
                                          |  ## Asset inventory
                                          |  Control asset inventory. ...
                                          |  [ Open ] [ Copy ]

5. Tiles, meters and badges

A tile is kpi_label, a number kpi_value (a JSON number, never text), and optionally kpi_unit (up to 4 characters), kpi_max (draws the meter), kpi_note, kpi_foot (up to 80) and kpi_badge. A tile with a label and no number is refused. In config.json the badge is a list of rules, first match wins. The row schema also takes badges, up to 4 of {label, tone}.

config.json: the tile
"tile": {
  "label": "Progress", "value": "progress", "max": 100, "unit": "%",
  "note": "of the work", "foot": "created for {control_id}",
  "badge": [
    { "if": "status==done", "badge": "DONE" },
    { "badge": "IN PROGRESS" }
  ]
}
Row
{
  "title": "Confirm encryption at rest (EU)",
  "subtitle": "In progress · Jordan L. · due 2026-05-01",
  "pane": "tasks",
  "kpi_label": "Progress",
  "kpi_value": 52,
  "kpi_unit": "%",
  "kpi_max": 100,
  "kpi_note": "of the work",
  "kpi_foot": "created for C-001",
  "kpi_badge": "IN PROGRESS"
}
App file: the overview and list tiles
right_widget:
  kind: cards
  mode: list_data
  bind:
    layout: tiles
    title: "{{row.kpi_label}}"
    value: "{{row.kpi_value}}"
    unit: "{{row.kpi_unit}}"
    max: "{{row.kpi_max}}"
    subtitle: "{{row.kpi_note}}"
    badge: "{{row.kpi_badge}}"
    footer: "{{row.kpi_foot}}"
Layout
  Progress                       IN PROGRESS
  52 %  [#####-----]  of 100
  of the work
  created for C-001

6. Row actions: open and copy

url on a row (http or https only) is opened by Enter. The buttons in the panel are declared once in the yaml with an id, bound to row fields, and listed by id in the panel. A row may add up to 3 actions of its own (row schema maxItems 3). The footer shows 6 buttons in all, the buttons in the app file first, and cuts each label at 14 characters (the full label, up to 40, is the tooltip). The template declares 2 (Open, Copy).

Row
{
  "title": "Trust portal · on",
  "subtitle": "trust.example.com/acme-demo",
  "icon": "globe",
  "url": "https://trust.example.com/acme-demo",
  "copy_text": "- Trust portal on - trust.example.com/acme-demo",
  "open_url": "https://trust.example.com/acme-demo"
}
App file
actions:
  - { id: open, kind: url, target: row, label: Open, url_template: "{{row.open_url}}" }
  - { id: copy, kind: composer, target: row, label: Copy, insert: "{{row.copy_text}}" }
# a panel lists the ids it shows:   actions: [open, copy]
Layout
> Trust portal · on                 Enter opens the page (row url)
  trust.example.com/acme-demo
                                    Right panel footer:  [ Open ] [ Copy ]
                                    Open  -> open_url
                                    Copy  -> copy_text, a safe plain text version

The template contract.

What you or your agent may edit, and what it must leave alone.

FileRuleWhat is in it
scripts/config.jsonEditApp id, chip, title, icon. base_url, key variable name, .env path, auth header. endpoints and their map. stats, overview, views, labels, tiles, fields, body, link, children.
scripts/fixtures.jsonEditOne real (made-up if sensitive) response saved per endpoint. check runs on it ("fixture": true in check.json) so tests need no key and no network. The shipped app is live.
bolt-app.json, README.mdEditTitle, role, summary, author, permissions in plain words. Keep id equal to the one in config.json.
check.json, golden/Edit, then regenerateAdd a case for each view you add. Run check --update-golden and read the diff once.
utilities/<id>.yamlGenerate onlyWritten by engine.py --emit-yaml. Never hand edit: the labels in the right panel must match the row fields.
scripts/engine.pyDo not editThe same file in every app built from the template. It reads config.json and fixtures.json from the folder it sits in, calls the API, keeps the cache and writes the rows. It is the only script the app file names.
scripts/bolt_app_kit.py and bolt_app_kit.lock.jsonDo not editThe vendored kit. Refresh it with bolt-apps kit vendor --flat ., never by hand.

Checking, icons and limits.

TopicRule
Sample mode in check"fixture": true at the top of check.json (every case) or on one case. A case wins; "fixture": false forces live. check then reads fixtures.json. A shipped app is live and a pack cannot be flipped.
Copied template, stale goldensA copy brings its golden/ files and check.json cases. Rewrite the cases, delete goldens no case names (golden_stale), run check --update-golden once and read the files.
IconsEvery icon in config.json must be a name in kit/schema/icons.json. An unknown one is an engine error and a lint --personal error (icon_unknown). The app file's own icon: is only a warning.
Stubs by argumentA stub can answer by the words after the command (by_args), so git status and git log can differ. A case can set env (capital names, not PATH or HOME). Otherwise the check environment is empty except PATH (the stub folder) and HOME (a temporary folder).
PermissionsThe list computed from the app files wins. permissions in bolt-app.json is listing text, and lint warns permissions_differ when they disagree.
Filters in labels{field|when} (epoch seconds or milliseconds, local date and time), whenday (date only), round, round1, round2 (0, 1 or 2 decimals), plus human, day, hhmm, upper, lower.

Limits of the engine templates

LimitWhat to do
List sizeThe engine hands a list at most 50 rows and says so in the view. A chart or table pane can draw up to 500 rows, but the engine does not give it more.
No per-id detail callViews mode calls only the list endpoints you name. {id} and {query} paths work only in lookup mode. Put detail fields in the list response, use a lookup app, or use a script like repo-radar.
Row buttonsConfig gives Open (url on an item) and Copy. More need the app file's actions:, at most 3 footer buttons including those two.
StitchingStats from several endpoints on the overview, and children (rows of another view whose field equals this row's id). There is no cross-join of two endpoints into one row; use a script (repo-radar, around).
Words before the view wordA nav arg is one plain token, no slash. If a query word comes before the view word it needs a plain-word default (lint view_arg_lead_default). A default of - is fine after it.
A button in a drilled-in viewA nav row carries no actions. A workaround is an ordinary row with a utility action that points at the app's own chip. That is not yet proven in the launcher.

Rules Bolt enforces.

These are checked when Bolt loads or runs the app, not by this page. The words in the middle column are what Bolt shows, so you can search for them. bolt-apps lint --personal, check and verify catch most of them before you drop the pack; the last step, running it in Bolt, catches the rest.

RuleWhat Bolt saysFix
The scripts folder is named in one plain formBolt cannot tell exactly which files this app runs, so it was not run. It names its scripts folder in a form Bolt cannot resolve to one file each, so it cannot say which files this app runs.Every mention of scripts_dir, comments included, is {{scripts_dir}}/<file> as its own word. The file name is letters, digits, ., _ and -, no leading or trailing dot, no ...
A named script exists and is a plain file<name> is missing, or is a link, not a file, or is not a plain file, or is too large to check (over 2 MB)Put each script directly in scripts/ as a real file under 2 MB.
No character escapes in the app fileIt uses character escapes (such as \x or \u) that can hide what it runs.Write plain text. The generated file has none.
Name every helper file in the commandNothing is said. Bolt hashes only the app file and the scripts named as {{scripts_dir}}/. An edit to a file the command does not name is not seen, so it does not ask for your OK again.The template names its helper files (config.json, fixtures.json, bolt_app_kit.py) as extra words in the command. Keep them, and add any helper file you add. Pack again after any edit.
First run needs your OKNot run. Needs your OK. Press Enter on the app's run row to review it and accept. Runs with your permissions. Not sandboxed.Press Enter on the app's run row and accept. Do this once, then confirm the first run works.
The app file changed after Bolt loaded itThis app's file changed after Bolt loaded it, so it was not run. Press Reload in Settings, Desktop, User Apps.Press Reload.
At most 8 views, overview includedpresentation.views has N entries, at most 8 allowedShow a detail with the same view and an id as arg, not a new view.
View namespresentation.views name "x" must match ^[a-z][a-z0-9_-]{0,23}$ and not be a reserved nameLowercase, starts with a letter, up to 24 characters. Not constructor or prototype.
view_arg and views go togetherpresentation.view_arg is set but presentation.views is missing, or the other way roundSet both. view_arg names an arg.
view_arg is a query wordpresentation.view_arg "x" is not a declared arg, or must name an arg bound with from: "query.word(N)"Declare args: [{ name: view, from: "query.word(0)" }].
Args come only from the typed wordsargs[x].from ... unsupported; only query.word(N) is supported in v1Use query.word(N).
Nav view and arg are plain tokensNothing is shown: Bolt silently drops a nav it cannot read.view must be a key of presentation.views. view and arg match [A-Za-z0-9_][A-Za-z0-9_.-]{0,63} with no ... A row with a utility action gets no nav. Every query.word before the view word needs a default that is also such a token (a default of - is not), or no row in the app gets a nav, Back included. Keep view_arg on query.word(0), as the templates do.
A command for each OS you supportbridge.command must define at least one of macos/linux/windows. On a missing one, at run: no bridge.command variant defined for <os>The template gives all three. Keep them.
One program, no shellbridge.command.<os> contains forbidden shell metachar, or is not argv-splittable, or references a variable inside double (single) quotes, or has an unterminated {{, or a malformed variable placeholderRemove ; && || |, backticks, $( and quotes around {{variable}}. Put steps in the script.
Timeout 1 to 60 secondsbridge.timeout_seconds must be 1..=60 (got N). Without the field Bolt waits 10 seconds.The template sets 25.
parse is json, lines or rawbridge.parse "x" not in [json, lines, raw]Use json.
The right block for the runtimeruntime: bridge requires a `bridge` block, or runtime must be one of [bridge, http_local, transform]Use runtime: bridge with a bridge: block.
No company-only fields<field> is not allowed in a user utility (admin-only field)Remove it. This includes cache_ttl_seconds.
Unknown keys are refusedunknown fieldRemove or fix the key.
A newer pack than the installed oneBolt did not install <name> <version>: version <old> is already installed, and a pack is only replaced by a newer version.Pack with a higher --version. To go back to an older version, remove the installed app first: Settings, Desktop App, User Apps, the Remove button on the app's row. If a personal app shows no Remove button in your build, only Review and accept or Decline, there is no other removal path today: raise the version instead.
Row links and labelsThe launcher refuses a link that is not http or https, or over 2048 characters, with no app file error. A button label is cut at 14 characters.Keep links to a public https:// address.
Row action kindsThe launcher refuses it, with no app file error: a row's own action must be url, composer or utility. run exists only in the app file.Declare buttons once in the app file and list them by id.

Pitfalls.

PitfallWhat to do
More than 8 viewsThe launcher refuses the app file. Overview counts as one, so 7 lists. Nest a detail inside an existing view with children instead of adding a view.
Looking for a filter fieldThere is none in the row. A filter is the second word you type, which becomes arg.
Scripts in a folderA personal pack takes single files directly in scripts/. The kit is one file, bolt_app_kit.py, not a folder.
A folder name that is not the idlint says id_mismatch. Name the folder after the id (~/my-app for my-app).
Packing again with the same versionBolt says "version 1.0.0 is already installed, and a pack is only replaced by a newer version. To go back to an older version, remove the installed apps first." Pass a higher --version on every pack.
A HIGH RISK rating at installExpected for a personal app. Any app that runs a program (tier 3) is rated high: Bolt lists "runs a program on your computer". The template's Open button uses {{row.open_url}}, which adds a second line, "opens links that are not fixed https addresses". Read the permissions, then confirm if you trust the app.
Writing scripts_dir anywhere elseEvery mention of scripts_dir in the app file, in a comment too and in any letter case, must be {{scripts_dir}}/<file> as its own word with no quotes and no spaces inside the braces. Otherwise Bolt says it cannot tell which files the app runs and never runs it. The generated file already does this; do not add comments that name it.
Fancy YAMLWrite plain YAML: bare keys, values on one line, no anchors, tags, | or > blocks, no tabs. The engine already writes it that way; do not hand edit it.
Tier 3 in the galleryAn app that runs a script and calls the network is tier 3. The public gallery does not accept it. Ship it as a personal pack.
Paging and writesThe engine reads the first response of each path, a list is capped at 50 rows, and it only does GET.
SecretsNever put the key in config.json, fixtures.json or a row. It comes from the system keychain or a chmod 600 .env file, not from a shell variable.

Have your agent do it.

Paste this to your coding agent and fill in the API. The steps and checks are in the Agent guide (plain Markdown).

Prompt for your agent
Read https://sparcle.app/docs/extend/agent-guide.md, section 13, "Build a rich app from the portal template".
Then build me a Bolt App for <API name and docs URL>.
Follow its steps exactly and run every check it lists.
Give me the .boltpack path and one install line.