1---2title: "Macros"3sidebar_position: 114---56# Macros78Macros repeat work: record what you do once, then run it again with a9key. They work like Google Sheets' Extensions > Macros, under10**Data > Macros**. A macro is a [Starlark](https://github.com/bazelbuild/starlark)11script (a small, deterministic dialect of Python) saved in the `.012`12file, as Sheets saves Apps Script with a spreadsheet. Recorded macros are13scripts too, so you can read them, change them, or write your own.14151617## Recording18191. **Data > Macros > Record macro** (or search the palette for "record").20 `REC` appears beside the mode indicator, and the context line says21 what's being recorded.222. Do the work: type entries, move and select, run commands from the23 menus, keys or palette, paste, drag the fill handle or a column border.243. **Data > Macros > Stop and save recording**. Name the macro on the25 context line, then give it a shortcut digit, or leave it empty. Esc at26 either question goes back to recording; **Discard recording** stops27 without saving.2829Two ways to record, as in Sheets:3031| | Recorded as | Replays |32|---|---|---|33| **Record macro** (absolute references) | `select("B3")`: the cells you selected | On the same cells, wherever the active cell is |34| **Record macro with relative references** | `move(0, 1)`, `extend(2, 0)`: steps from the active cell | From wherever the active cell is when you run it; formulas typed move with it, as in a copy, and Ctrl+arrows, Home, Ctrl+Home and Ctrl+End are recorded as `jump()`, since where they land depends on the data |3536What gets recorded:3738- entries as they're accepted (`enter("=SUM(B2:B8)")`), including39 Ctrl+Enter over a selection (`fill=True`);40- the selection, only when something acts on it: pressing Down five times41 then typing records one `move(0, 5)` (or one `select()`), so a replay42 doesn't depend on the size of the window;43- commands that change the sheet, by id (`run("format.bold")`), with the44 answer to the question they ask, if any45 (`run("column.width", answer="15")`, `run("sheet.delete", answer="enter")`);46- pasted text (`paste_text(...)`), the fill handle (`fill(...)`), column47 borders dragged or fitted (`set_width(...)`) and tabs dragged48 (`move_sheet(...)`);49- what you choose in dialogs, as the command that opens the dialog with50 your choices as its answer: the sort bar51 (`run("data.sort_range", answer={"by": [{"column": "B"}], "header": True})`),52 the filter picker's values and condition, find and replace, the chart53 editor, and the pivot editor, each as the dialog left things when you54 pressed Enter. These name columns, ranges and cells as they were, with55 either kind of references;56- charts moved or resized, by keys or by dragging, as57 `run("chart.edit", answer={"chart": 1, "at": "F3"})`, one call for a58 move made in steps;59- rules added, edited, removed or moved in the conditional formatting and60 data validation panels, as the commands that do it from a line of the61 file (`run("format.conditional_add", answer={"ranges": "B2:B9", ...})`,62 `run("format.conditional_remove", answer=2)`), and items picked from a63 dropdown, as entries.6465What doesn't: undo, and changes made in the named ranges picker. Anything66like that which changes the workbook is noted in the script as a comment,67`# Not recorded: undid: sort A2:C9`, so the script never silently does less68than you did. Files, menus, help and other macros are never part of a69macro.7071## Running7273- **The shortcut**, Ctrl+Alt+Shift+digit, in READY. Terminals without the74 kitty keyboard protocol send it as Ctrl+Alt with the shifted symbol75 (`Ctrl+Alt+!` for 1 on a US layout), which works too.76- **Data > Macros > Run macro**, a list of the saved macros.77- **The palette** (Ctrl+K): type the macro's name.7879A run is one undo step: Ctrl+Z undoes everything the macro did. While it80runs, the mode indicator says `CMD` (as 1-2-3 did), keys and the mouse81wait, and **Esc stops it**; what it did so far stays, and Ctrl+Z undoes it.82When it ends, the context line says `Ran Totals`, or the last line the83script printed, or where it failed:8485```86Totals:3:5: get: not a cell or range: ZZ Ctrl+Z undoes what it did87```8889(`Totals` is the macro's name, `3:5` the line and column in its script.)9091Every run has a limit of 10 million Starlark steps, so a script that loops92forever stops within a second or so with93`stopped after 10000000 steps: does it loop forever?`.9495## Managing9697**Data > Macros > Manage macros** lists the saved macros with their98shortcuts:99100| Key | Action |101|---|---|102| Enter | Run the highlighted macro |103| F2 | Rename it |104| F3 | Change its shortcut: a digit, or empty for none |105| F4 | Edit its script in your editor |106| Ctrl+D | Delete it (Ctrl+Z brings it back) |107| Type | Search by name |108109The first row, **+ Write a macro** (also **Data > Macros > Write a110macro**), names a new macro and opens a script for it in your editor.111112Editing uses `$VISUAL`, then `$EDITOR`, then `vi`, with the screen handed113over until the editor exits; the script is saved when it does. If it has114a mistake, it's saved anyway and the context line says where115(`Saved Totals, but it has a mistake at Totals:4:1: undefined: sett`), so116you can fix it with F4. Sessions served over SSH don't start an editor:117their macros can be recorded, run, renamed and deleted, not edited.118119Changes to macros (recording, renaming, deleting, editing) are undo steps120and mark the file modified, like any edit.121122## Macros from other computers123124Opening a file never runs its macros. The file remembers which computer125its macros were made or trusted on (a random id kept in 012's126config directory, the one [Configuration](../reference/config.md) describes). Running127a macro from a file made elsewhere asks once, on the context line:128129```130Trust this file's macros? Enter Run Esc Cancel131```132133Enter trusts all of the file's macros for this session and, once the file134is saved, on this computer. Sessions served over SSH have no id of their135own, so they ask once per session.136137Scripts can't read or write files, reach the network, start programs, or138read the clock or random numbers: all they can reach is the functions139of the [scripting API](../reference/macro-api.md). What a macro can do is140what you could do with the keyboard in that workbook, which is why it141asks before running someone else's.142143## Writing your own144145**+ Write a macro** in Manage macros opens a new script in your editor.146The [scripting API](../reference/macro-api.md) lists the functions147scripts call and the command ids they run.