MoonwalkDocs

Tools

The 98 tools Moonwalk gives Claude and ChatGPT, by area. This page is written from the list the connector serves, so a tool is here exactly when an agent can call it.

Each tool is labelled by what it does to your base:

Claude and ChatGPT ask you before any Changes tool.

Each description is the one the agent reads, word for word, so “you” in it is the agent.

Boards · Tables & data · Actions · Groups · Files · Connections · Versions & trash · Moonwalk

Boards

Get a board

get_board Reads

Returns one board: its name, width, whether notifications are on, whether its view link is published and who it opens for, and its path, whether its folder is empty or behind, its slides in order (null while it is drawn at its width), its screen's declaration — each run with what it takes and answers — and what it is built on: the tables it reads, the actions behind it, the connections those use. Its files are list_board_files's.

List a board's errors

list_board_errors Reads

Lists what went wrong with a board's screen, newest first, each with its kind: undeclared_data and undeclared_run for a read or run its declaration never named, action_gone for a declared run whose action has left, render for a screen that threw, compile for a save whose folder did not build. A run's own failure is not here — get_run has it. limit is capped at 200.

List a board's files

list_board_files Reads

Lists every file in a board's folder, by path, with its size in characters.

List boards

list_boards Reads

Lists every board of the base, in the rail's order, with its group, its view link's ref, whether that link is published and who it opens for while it is. A link that is not published opens for nobody, whatever visibility says.

Look at a board

screenshot_board Reads

Takes a picture of a board as a visitor sees it — its screen at its width, drawn from the rows it reads now — in a window 1280 pixels wide. The same picture a save that builds answers with, without saving. Who may view the board changes nothing: it stays as it was. Nothing is written and no run is fired: while it draws, every run is refused not while previewing.

More

A board taller than 1200 pixels comes back one page at a time: the answer says page of pages, and page: 2 is the next 1200 pixels, and so on to the end. Each call draws the board afresh. A page past the last is refused, naming how many there are. theme picks light (the default) or dark. On a board of slides, slide (from 1, the first by default) picks which slide is drawn, at 1280×720. thrown is anything the screen threw while it drew. When it cannot be drawn the answer is {"screenshot": {"unavailable": <reason>}}.

Read a board's file

read_board_file Reads

Reads one file of a board's folder, whole.

Search a board's files

grep_board_files Reads

Finds every line in a board's folder pattern matches — a Python regular expression — as {file, line, text}, at most 200.

Search boards

search_boards Reads

Finds boards whose title holds q — the sidebar's filter.

Create a board

create_board Adds

Creates a board, at the end of group_id (list_groups), or of the tab's default when that is left out: a name and an empty folder, which draws *This board is empty.* until you write its App.tsx with write_board_file. Every board is at the top level. It starts members only, medium wide, notifications off. The id is yours to mint. kind: library makes a library instead, which counts as a board.

More

A library holds parts the base's boards import: components, functions and values, colours and line widths among them. create_board with kind: library makes one, when the person wants one, or when two boards should share a part; it stays a library, and no board becomes one.

- **What it offers is exactly what its index.ts exports**, a .ts file, so no JSX in it: components live in .tsx files beside it, and it re-exports them, export { Stat } from './stat'. A board imports it by its internal name, import { Stat, brand } from '@lib/ui-kit', and nothing deeper: any other name, or a path past it, is a compile error. get_board has the name, made from the library's first name; set_library_name changes it and rewrites every importing board's @lib/ lines in the same write. The name the person sees is its title, and touches no import - A library imports what a board may and its own files, and never @lib/. Code only, .ts and .tsx: it points at a picture in Public/ by publicUrl('logo.png') - **App.tsx is its storybook**, a screen drawn above the list of what it offers: each part shown as it draws, with values written in the code. It reads no table and fires no action, so a library has no declaration, no width, no slides and no view link. Without App.tsx the page shows the list alone - A save reaches every board using it: each rebuilds. A library save that does not build leaves them drawing their last good build, behind, so a library is left only once it builds. A library some board imports cannot be deleted (409 library_in_use, naming them) - Look and feel are the person's: a library is where a base keeps its own colours and type, and boards that import them draw in them

Restore a board

restore_board Adds Reaches outside

Brings a board out of the trash, at the end of its group, as it was: its view link opens again, for whoever it did before. list_trash names what is there.

Delete a board

delete_board Changes

Trashes a board with its folder. restore_board brings it back; list_trash with board shows it. While it is in the trash its view link answers not-found. One with no name and nothing in its folder that nothing but your own open sitting ever touched is deleted outright instead, and has no way back.

Delete a board's file

delete_board_file Changes

Removes one file from a board's folder and compiles the rest — answered as write_board_file is. The last file gone empties the board, its declaration with it: it draws *This board is empty.* again, and a folder written after needs set_board_declaration again before it reads or runs anything. A board is rebuilt by writing over its files, not by deleting them all.

More

Every write, edit and delete saves the file, whatever it holds, then compiles the whole folder. The answer is built and errors, each {file, line, column, text} — or, once it builds, screenshot: page 1 of the board as drawn now — of the slide the file draws, when it draws one — from its real rows, in theme (light, the default, or dark), and thrown, every message the screen threw while it drew. While the folder does not build the board keeps drawing its last good build and says it is behind. While it draws, every run is refused not while previewing, so a picture never writes to the base. When it cannot be drawn the save still stands, and screenshot is {"unavailable": <reason>}. Your run of saves on one board is one version in its history. **Every save must carry a change_description**: one line, in words a person would understand, saying what changed: "Shows the week's total above the chart". It is the line the board's history shows, and a save without one is refused (422 change_description_required).

Edit a board's file

edit_board_file Changes

Replaces old with new in one file of a board's folder, leaving the rest byte for byte, and saves it — answered as write_board_file is. old must appear exactly once unless replace_all: enough of the lines around it make it unique. A refused edit saves nothing, edit_refused.

More

Every write, edit and delete saves the file, whatever it holds, then compiles the whole folder. The answer is built and errors, each {file, line, column, text} — or, once it builds, screenshot: page 1 of the board as drawn now — of the slide the file draws, when it draws one — from its real rows, in theme (light, the default, or dark), and thrown, every message the screen threw while it drew. While the folder does not build the board keeps drawing its last good build and says it is behind. While it draws, every run is refused not while previewing, so a picture never writes to the base. When it cannot be drawn the save still stands, and screenshot is {"unavailable": <reason>}. Your run of saves on one board is one version in its history. **Every save must carry a change_description**: one line, in words a person would understand, saying what changed: "Shows the week's total above the chart". It is the line the board's history shows, and a save without one is refused (422 change_description_required).

Move a board

move_board Changes

Puts a board into group_id (list_groups), its own when null, after after, or first in the group when that is null.

Rename a library's import

set_library_name Changes

Sets a library's internal name, what boards import it by, @lib/<name>: lower-case letters, digits and -, 1 to 40, no other library's of this base, trashed ones counted. Every importing board's @lib/ lines are rewritten in the same write and each builds again, so none breaks; each is a version of its own. 422 library_name_invalid, 409 library_name_taken; nothing changes on a refusal. Answered with what the library offers and the boards using it.

Set a board's declaration

set_board_declaration Changes

Replaces what a board's screen may read and run, whole — never merged. Refused whole, naming every violation, when any of it does not hold (422 screen_invalid). Answered with the declaration as it now reads.

More

A declaration is data and runs, set with set_board_declaration. A screen reads and runs, and does nothing else — there is no way to write a row through a query, so a data entry has no mode and a declaration carrying one is refused.

Each data entry is two fields: sql and description.

The SQL is read-only Postgres over this base's views — "v_<hex>" for a table and "c_<hex>" for a column, both derived from ids, so a rename never breaks one. The screen reads each column by its alias, and names a row in a run only when id is selected. A read hands over at most 200 rows.

The description is for the person, not for you: what the query asks, in the words someone would use to ask for it. The SQL is hex and nobody can read it, so this is the only readable record, and an entry without one is refused.

Each runs entry is the screen's name for it → the id of an action that already exists in this base. Its trigger must be manual: a cron or webhook trigger fills its own payload, so a screen has nothing to supply. useRun('move')(input) fires it with input as the trigger's output, so input has to fit that trigger's output_schema: get_board reports each run as {action_id, action_name, input_schema, output_schema}, the last being what the run's output holds. The action is built first and bound after; there is no way to make one from here.

Set a board's notifications

set_board_notifications Changes

Turns a board's notifications on or off. Off on every board until turned on: while off, an action's boards.notify to it is refused notifications_off and its bell is not drawn, in the app or on its view link. This call turns them on only when the person wants an automation to post to the board, and the person is told it did.

Set a board's slides

set_board_slides Changes

Sets a board's slides, the whole list in order, each {name, file, notes} — name what the person's list shows (1 to 80 characters), file a .tsx file of the folder that default-exports the slide's screen, one slide each, notes the speaker's notes beside it in the presenter view, plain text: what the speaker says, not what the slide shows. Left out, a slide keeps the notes it has; "" clears them — or null: drawn at its width again, from App.tsx. Adds, removes, reorders and renames in one call: the list sent is the list as it should be. A slide the list drops takes its file with it unless another file imports it. Null only at one slide (slides_left); App.tsx then re-exports its file. Compiles once; answers as a save does. Part of the board's version.

Set a board's width

set_board_width Changes

Sets how wide a board is drawn: mobile (400 px), medium (640 px), wide (960 px), full (the page's whole width, drawn as the page, no card). Its height is always what its screen draws. Every open copy redraws at once. Part of the board's version. On a board of slides it turns them off first, and only at one slide (slides_left).

Set who can view a board

set_board_visibility Changes Reaches outside

Sets a board's view link, /b/<name>-<token>: the board alone, read-only. published turns it on or off: off, the default, it opens for nobody, members included. visibility is who it opens for while on: members of this base, signed in, or anybody with the link, signed in or not — public — and is kept while it is off. Either or both may be sent. The link never changes: only the token is read, so a rename never breaks one already handed out. The answer's path is that link. A board is published only when the person asked for it to be shared, and made public only when they asked for anybody to open it: a members link still needs publishing to open.

Write a board's file

write_board_file Changes

Writes one file of a board's folder whole, new or replacing what is there. To change a few lines, edit_board_file sends less.

More

A board is one screen, built from a folder of files you own. No text, no blocks: what the board shows is what its folder draws, and a board that wants words draws them.

- App.tsx is the entry and default-exports the screen. Other files are yours to lay out, reached relatively or through @/ from the folder's root, as shadcn/ui's own code does: @/components/ui/button, @/lib/utils. A path is relative and ends in .tsx or .ts - Imports allowed: react, @moonwalk/widget (the bridge: useQuery, useRun, …), radix-ui, class-variance-authority, clsx, tailwind-merge, lucide-react, and the folder's own files. Nothing else resolves, and nothing installs a package: any other import is a compile error naming the file and line - shadcn/ui is not preinstalled: the component files a board uses are written into components/ui/ (and cn into lib/utils.ts), as npx shadcn add would, and are free to change. Two boards wanting one part share it through a library (below), or each carry a copy. Its theme tokens — bg-background, text-foreground, text-muted-foreground, bg-primary, bg-card, border, ring, … — start in the app's colours, light and dark (dark: follows the app). They are a default, not a rule: a board or a library may set its own colours and type, and one that does draws its dark side itself, off useTheme() - Tailwind for style. The page adds no padding: the card the board is drawn on has none and the screen's ground is transparent, so every gap is yours. The board is as tall as the screen draws: never h-screen or min-h-screen, which have no height to fill - Width is how wide the board is drawn, the person's menu choice or set_board_width: mobile (400 px), medium (640 px), wide (960 px), full (the page's whole width, drawn as the page, no card). medium unless set. A board is designed for the width it has - Slides is the other layout, the person's Layout › Slides or set_board_slides: the board's slides in order, each {name, file, notes}, a file of the folder that default-exports its screen, as App.tsx does, and the speaker's notes, which only the presenter's own window shows. The page draws one at a time with a ‹ 1 / 3 › switcher; null is drawn at the width again, from App.tsx. A slide is a fixed 1280×720 canvas, as a PowerPoint slide: laid out at that size whatever the window, then shrunk, text and all, to fit; what draws past 720 is cut, and one drawing less is centred. Each slide is designed for 1280×720; the width does not apply while slides are on. A slide is added by writing its file, then setting the list with it in, and removed by setting the list without it; its file goes too unless another file imports it. A file that draws a slide is not deleted on its own. get_board has the list - A folder mid-build may not compile yet: one call writes one file, and the save of App.tsx, written last, answers with the build's errors - A library, kind: library on get_board, is a folder too, written with these same tools. Its parts are what other boards import, and create_board says how.

Every write, edit and delete saves the file, whatever it holds, then compiles the whole folder. The answer is built and errors, each {file, line, column, text} — or, once it builds, screenshot: page 1 of the board as drawn now — of the slide the file draws, when it draws one — from its real rows, in theme (light, the default, or dark), and thrown, every message the screen threw while it drew. While the folder does not build the board keeps drawing its last good build and says it is behind. While it draws, every run is refused not while previewing, so a picture never writes to the base. When it cannot be drawn the save still stands, and screenshot is {"unavailable": <reason>}. Your run of saves on one board is one version in its history. **Every save must carry a change_description**: one line, in words a person would understand, saying what changed: "Shows the week's total above the chart". It is the line the board's history shows, and a save without one is refused (422 change_description_required).

The <Screen> provider is mounted around App for you; a screen never renders one. useQuery gives {rows, broken} and nothing that writes. There is no token: the broker is the only way to the base, and localStorage is the reader's browser's, not the base's. Anything else loads from any https address, an image, a font, media, an embedded page or a fetch, but never a script, and the picture a save answers with loads none of it.

A screen, App.tsx:

import { useState } from 'react'
import { publicUrl, signInState, useFocus, usePage, usePalette, useQuery, useRecorder, useRun, useRunResult, useScroll, useTheme } from '@moonwalk/widget'
import { Button } from '@/components/ui/button'
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'

export default function App() {
  const tasks = useQuery('tasks')      // a key of the declaration's data
  const move = useRun('move')          // a key of the declaration's runs
  const collect = useRunResult()       // a run answered `strt`, asked again by its id
  const theme = useTheme()             // 'light' or 'dark'
  const palette = usePalette()         // the app's pencil colours, in that theme
  const scroll = useScroll()           // 0 → 1 as the page scrolls the board past
  const focus = useFocus()             // false while the reader is in another window
  const page = usePage()               // the page's address, '' until it arrives
  const mic = useRecorder()            // { recording, start(), stop() → File }
  const note = useRun('note')          // a run whose trigger takes a file
  const [said, setSaid] = useState('')
  const press = () =>
    (mic.recording ? mic.stop().then((audio) => note({ audio })) : mic.start())
      .catch((e) => setSaid(String(e)))  // mic_denied, mic_unavailable
  const signIn = async () => {          // a sign-in's state is signInState()'s, never the page's
    const to = new URL('https://accounts.google.com/o/oauth2/v2/auth')
    to.searchParams.set('state', await signInState())
    window.top!.location.href = to.href  // with its client_id, redirect_uri, scope
  }
  if (!tasks.rows) return <p className="p-6 text-muted-foreground">Loading…</p>
  return (
    <Card className="m-4">
      <CardHeader><CardTitle>Tasks</CardTitle></CardHeader>
      <CardContent>
        <audio src={publicUrl('theme.mp3')} controls />  {/* /files/Public/theme.mp3 */}
        <Button onClick={press}>🎤</Button> {said}
        <Button onClick={signIn}>Sign in with Google</Button>
        <ul>{tasks.rows.map((t) => <li key={t.id}>{String(t.title)}</li>)}</ul>
      </CardContent>
    </Card>
  )
}

useRun gives a function resolving to {run_id, status, returncode, output}. status is fin (it ended) or strt (still going past the server's 3-second wait — not a failure). fin alone does not mean it worked: success is status === 'fin' && returncode === 0. rej never reaches a screen — a refused run rejects the promise instead.

output is the JSON object the action's last step returned — its ReturnType — so a field is read off it: run.output.message. It is null while strt and when the last step failed, and past 16 KB it is {"$over": <bytes>}: a run answers, it does not hand over a dataset. get_board reports each run's output_schema. A run answered strt can be collected later: useRunResult()(run.run_id) resolves the same shape.

A run may take a file. A trigger property marked {"type": "string", "format": "file"} takes one, and a screen passes a File at the top level of input — useRun('import')({ book: file, language: 'en' }). It goes as bytes in the one request, is saved into /files/Uploads/, and the step is handed the path it was saved at. Nothing in the SDK is new for it: an <input type="file"> and the File it yields.

This is the one thing you cannot do yourself — fire_action names a path because MCP carries no bytes, and the browser is the caller that sends them. A file past 100 MB is refused, 413 too_large.

A screen records the person's voice with useRecorder(): start() turns the mic on, stop() resolves with the recording as a File — recording.webm, .mp4 or .ogg, whichever the browser records. recording says which press is next. The screen draws its own button: a press starts the recording, a press or a release stops it. The file goes to a run as any file does, useRun('note')({ audio: await mic.stop() }), and plays back from URL.createObjectURL(file). One recording at a time, cut at five minutes or when the tab is hidden; recording stays true through a cut, and stop() still hands over what was caught. start() rejects mic_denied or mic_unavailable, which lands on the error stream as a throw unless the screen catches it and says so. In a picture it rejects not while previewing, as a run does.

A screen loads a file from the base's Public/ folder by naming it: <audio src={publicUrl('theme.mp3')} controls /> plays /files/Public/theme.mp3. Images and fonts load the same way, and <a href={publicUrl('report.pdf')} download> saves one. Only files in Public/ can be named like that, and anybody can open them, signed in or not, so moving a file in is publishing it. The picture a save answers with does not load them.

Tables & data

Get a table

get_table Reads

Returns one table and every column on it, with each column's type.

List a table's rows

list_rows Reads

Lists rows of one table, by limit and offset. Filtering, sorting, grouping and joining are SQL's, run_sql. The table screen's own filter is the UI's and adds nothing an agent holding SQL does not already have.

List tables

list_tables Reads

Lists every live table in the base, in the rail's order, with its group.

Run read-only SQL

run_sql Reads

Runs read-only SQL against this base's tables. Ordinary Postgres — joins, GROUP BY, date_trunc, window functions, now().

More

Names are physical and derived from ids, so a rename never breaks a query: a table is the view "v_<hex>" (get_table gives the ids; the hex is the uuid without dashes) and a column is "c_<hex>". Rows are writable or numbered only when id is selected. A select/multi_select value is an option id, not its label.

Writes are refused by the database itself, not by a check here: there is one role per base, granted SELECT on its views and nothing else. Changes go only through write_rows.

Add a column

add_column Adds

Adds a column to a table.

Create a table

create_table Adds

Creates a table and its columns, at the end of group_id (list_groups), or of the tab's default when that is left out.

Restore a column

restore_column Adds

Takes a dropped column back under the same id, with every value it held. Every stored query naming it runs again with no edit.

Restore a table

restore_table Adds

Brings a trashed table back, at the end of its group, if its name is still free.

Change a column's type

change_column_type Changes

Changes a column's type. Refused, naming the rows that stopped it, when a value would not survive the cast.

Delete a column

delete_column Changes

Drops a column. Never refused — every query naming it stops running and says so. restore_column takes it back, with its values — and so do undo, to the place it held, and reverting the table to a version from before the drop.

Delete a table

delete_table Changes

Trashes a table. restore_table brings it back — unless the table held no rows and nothing but your own open sitting ever touched it, which is deleted outright and has no way back.

Edit a column

edit_column Changes

Renames a column, or sets a select's options. options is the full list: an option is kept by its id, relabelled under the same id, added with a label only and removed by leaving it out. Ids never change, so nothing naming them breaks. An option a row still holds cannot be removed.

Move a table

move_table Changes

Puts a table into group_id (list_groups), its own when null, after after, or first in the group when that is null.

Rename a table

rename_table Changes

Renames a table. Its columns and rows are untouched.

Write rows

write_rows Changes

Inserts, sets, deletes or restores rows of one table. One call is one transaction and one undo step, however many rows it touches. A new row lands last; rows are in # order and cannot be placed.

Actions

Get a run

get_run Reads

Returns one run: its status, its timings, what it received (input) and what it returned (output). Either is {"$over": <bytes>} past 16 KB.

Get a run's steps

get_run_steps Reads

Returns one row per executed step, in execution order — what you debug a run from. cpu_ms and wall_ms are what the CPU and wall-time limits count: every process it started, from the moment it was sent. Installing its dependencies comes first and is in neither, so a first run can take a minute and report a few hundred ms.

Get a step's config values

get_step_configs Reads

Returns what a step declares as config, and the values saved against it.

Get a step's connections

get_step_connections Reads

Returns what a step declares as connections, and which base connection is bound to each key.

Get a step's source

get_step_source Reads

Returns the Python source of one step, as it is on disk.

Get an action

get_action Reads

Returns one action: its step tree, its trigger and its state.

Link to a webhook's secret

get_webhook_secret Reads

Returns where the person gets a webhook trigger's signing secret, never the secret itself. The url is for the person: on that screen they press the eye on the trigger and copy the secret to paste upstream. secret_set is false while an upstream secret has not been pasted in.

Link to paste a webhook secret

set_webhook_secret Reads

Returns where the person pastes the upstream's signing secret, never the secret itself. The url is for the person: on that screen they paste it into the trigger. The secret must never pass through the conversation. Refused (409 system_generated) when Moonwalk made the secret; that one is copied, with get_webhook_secret.

List actions

list_actions Reads

Lists every action in the base, in the rail's order, with its steps, its trigger and its group.

List an action's runs

list_runs Reads

Lists an action's runs, newest first.

List an action's steps

list_steps Reads

Lists every step of an action, in tree order, with its inputs.

Create a step

create_step Adds

Adds a step. The source is linted at save: it must define a top-level run(...) and, for a code step, a ReturnType model it returns.

More

A code step's pseudocode is required: what it does, in plain words a person reads on the step. A code step made without it is refused (422 pseudocode_required).

Every save must carry a change_description: one line, in words a person would understand, saying what changed: "Skips weekends". It is the line the action's history shows, and a save without one is refused (422 change_description_required).

A positional parameter of run(...) is an input, filled from the step's inputs list in order. {"step": "trigger", "path": [...]} reads what fired the run; {"step": "<hash>", "path": [...]} reads an earlier step's output.

def run(title, file) -> ReturnType: ...
inputs=[{"step": "trigger", "path": ["title"]},
        {"step": "trigger", "path": ["file"]}]

A count that does not match, or the same names in a different order, is refused at save (422 invalid_step).

How actions and their steps work, the mw_sdk SDK included, is in read_overview.

A config (Config[T] on run) is a setting and never a credential. A key, password or token is a connection, asked for with request_connection.

Each step gets 1 hour of wall time and 120 CPU-seconds, counted across every process it starts. Past either it is killed, and its step run's error_type says which: wall_time or cpu_time.

Create an action

create_action Adds

Creates an action. The trigger's mode is set here and never again — a different mode is a different action. description is required: one line a person would understand, saying what it does. It is the line its card shows, and an action made without one is refused (422 description_required). It lands at the end of group_id (list_groups), or of the tab's default when that is left out.

More

A webhook trigger is the action's own URL, webhook_url: any HTTP address something calls, not only a service's POST. method is POST, the body as the payload, or GET, the query string as the payload, every value a string. reply is now, the run's id at once; wait, the run waited for up to 30 s and its output answered; or redirect, the same wait, then the browser sent to the board the run's output names. Both default to today's: POST, now.

A browser sent back is a webhook too: a sign-in provider returning to its redirect URI (Google's ?code=), a checkout's return (Stripe's success URL). Each is method: GET, reply: redirect, and its last step returns {redirect, session}: redirect the trigger's state, the page the screen left; session an opaque string, say a row's id in a sessions table. A sign-in's state is what await signInState() answers the screen, passed to the provider as it is, never usePage(): it ties the return to the browser that left, and the run reads state as the page's address. A session for a browser that did not start the sign-in is refused, 403. The session goes back under session and nowhere else: never in redirect's address (?session=), never in the screen's localStorage. The server keeps it in a cookie no script reads; an address with it signs in whoever opens the link, and skips the 403. That board's screen then carries it into every run it fires as session, which a manual trigger declares as {"type": ["string", "null"]} and looks up to know who is signed in, whatever the screen passes under that name; a run returning session: null signs out. The URL to register with the provider is the trigger's webhook_url, which the person pastes there. A GET takes no signature.

Restore an action

restore_action Adds

Brings a trashed action back, at the end of its group, its trigger live again.

Activate an action

activate_action Changes

Locks this exact version and allows it to fire. Needs steps — the version is always there, because every edit goes into one.

Clear a step config value

clear_step_config Changes

Drops one config value, back to the declared default.

Deactivate an action

deactivate_action Changes

Stops it firing and unlocks it for editing.

Delete a step

delete_step Changes

Deletes a step and everything under it — an if takes both branches. Refused while a step left behind reads one that goes, until that step is rewired or deleted.

Delete an action

delete_action Changes

Trashes an action. Its steps, runs, versions and files are kept and nothing fires it; restore_action brings it back with its trigger live. Refused while a board's screen fires it, naming the boards. One with no steps that nothing but your own open sitting ever touched is deleted outright instead, and has no way back.

Fire an action

fire_action Changes Reaches outside

Runs an action now, whether it is on or off. Returns the run id at once; what happened is read off the run. A file field ("format": "file") takes the path of a file already in the base — /files/Uploads/book.pdf; request_upload is how a file from your own machine gets there. You are the one caller that names a path; every other sender of a run, a board's screen included, sends the file itself. 422 file_not_found for a path that is not a file. Each step gets 1 hour of wall time and 120 CPU-seconds, counted across every process it starts. Past either it is killed, and its step run's error_type says which: wall_time or cpu_time.

Move an action

move_action Changes

Puts an action into group_id (list_groups), its own when null, after after, or first in the group when that is null.

Run code in the sandbox

execute_code Changes Reaches outside

Runs a Python snippet in this base's sandbox and returns its exit code, stdout and stderr. dependencies are pip requirements installed into a fresh venv; the first call for a given set takes about a minute. A snippet gets the same limits as a step: 1 hour of wall time and 120 CPU-seconds, counted across every process it starts. Past either it is killed, and killed_by says which: wall_time or cpu_time. cpu_ms and wall_ms are what the CPU and wall-time limits count: every process it started, from the moment it was sent. Installing its dependencies comes first and is in neither, so a first run can take a minute and report a few hundred ms.

Set a step config value

set_step_config Changes

Sets one config value, checked against the step's declaration. A config (Config[T] on run) is a setting and never a credential. A key, password or token is a connection, asked for with request_connection.

Update a step

update_step Changes

Replaces a step's name, source, dependencies or inputs. Every save must carry a change_description: one line, in words a person would understand, saying what changed: "Skips weekends". It is the line the action's history shows, and a save without one is refused (422 change_description_required). Each step gets 1 hour of wall time and 120 CPU-seconds, counted across every process it starts. Past either it is killed, and its step run's error_type says which: wall_time or cpu_time.

Update a trigger

update_trigger Changes

Edits the trigger within its mode: output schema, run-record limit, and that mode's own fields. The mode itself is fixed, and there is no on/off here: whether it fires is activate_action.

More

A webhook trigger is the action's own URL, webhook_url: any HTTP address something calls, not only a service's POST. method is POST, the body as the payload, or GET, the query string as the payload, every value a string. reply is now, the run's id at once; wait, the run waited for up to 30 s and its output answered; or redirect, the same wait, then the browser sent to the board the run's output names. Both default to today's: POST, now.

A browser sent back is a webhook too: a sign-in provider returning to its redirect URI (Google's ?code=), a checkout's return (Stripe's success URL). Each is method: GET, reply: redirect, and its last step returns {redirect, session}: redirect the trigger's state, the page the screen left; session an opaque string, say a row's id in a sessions table. A sign-in's state is what await signInState() answers the screen, passed to the provider as it is, never usePage(): it ties the return to the browser that left, and the run reads state as the page's address. A session for a browser that did not start the sign-in is refused, 403. The session goes back under session and nowhere else: never in redirect's address (?session=), never in the screen's localStorage. The server keeps it in a cookie no script reads; an address with it signs in whoever opens the link, and skips the 403. That board's screen then carries it into every run it fires as session, which a manual trigger declares as {"type": ["string", "null"]} and looks up to know who is signed in, whatever the screen passes under that name; a run returning session: null signs out. The URL to register with the provider is the trigger's webhook_url, which the person pastes there. A GET takes no signature.

Update an action

update_action Changes

Renames an action or changes its description. A blank description is refused (422 description_required); left out, the one there stays.

Groups

List groups

list_groups Reads

Lists a tab's groups in the rail's order: section is boards, actions or tables. Every board, action and table is in exactly one, named by its group_id. Each tab has one default, is_default, where a thing lands when nothing names a group; its name is null until somebody renames it, and it reads as the tab's own word.

Create a group

create_group Adds

Makes a group in a tab, after after or last when it is null. Everyone in the base sees it. A group holds what belongs together and is named for what it serves.

Delete a group

delete_group Changes

Deletes an empty group: 409 group_not_empty while it holds a live thing, 409 group_default for the tab's default, which is never deleted. What it holds in the trash moves to the default first.

Move a group

move_group Changes

Puts a group after after among its tab's groups, or first when it is null.

Rename a group

rename_group Changes

Renames a group, the default included. 1 to 60 characters, never blank.

Files

Find files by name

search_files Reads

Finds files and folders by a glob, without listing folders one by one. A pattern with no / matches a name at any depth (*.md); one with a / matches the path from path, ** descending (notes/**/*.md), or from the root when it starts /files/. Dotfiles are included. At most 100 answers. Documented at https://docs.moonwalk.now/tools.html#files.

List files

list_files Reads

Lists one directory of the base's tree. A path is absolute from /files, the root — /files/notes/todo.md — and every answer spells it that way. Documented at https://docs.moonwalk.now/tools.html#files.

Read a file

read_file Reads

Reads a file's text. An image comes back as a picture you can see: encoding image, and the picture, shrunk to 2000 px. Any other file that is not UTF-8, or is too large, comes back as binary with no text. Documented at https://docs.moonwalk.now/tools.html#files.

Search inside files

grep Reads

Finds lines matching a regular expression (Python re) inside the base's files, dotfiles included, and answers each hit's path, line number and text. Case-sensitive unless case_insensitive. path is the folder to search under; glob narrows which files are read, matched the way search_files matches. Binary files, files too large to preview and lines over 10,000 characters are skipped. At most 100 hits; truncated says there were more. Documented at https://docs.moonwalk.now/tools.html#files.

Get an upload link

request_upload Adds

Gets a one-time link for sending a file from your own machine into the base — MCP carries no bytes, so this is how one gets in. The answer is a command that sends the file once its path replaces the placeholder; the upload answers {"path": "/files/Uploads/…"}, which is what a file field in fire_action takes. The link works once, for 5 minutes. When the upload cannot connect, the note says what unblocks it.

Make a directory

mkdir Adds

Makes one directory, whose parent must already be there.

Restore a file

restore_file Adds

Puts a trashed entry back where it came from, under the name it had. id is a row's from list_trash, not a path. Refused when something is at that path now.

Delete a file

delete_file Changes

Moves a file, or a directory and everything in it, into the base's trash, where it waits 30 days. It leaves the tree — list_trash with kind="file" is where it is now, and restore_file takes the id from there and puts it back where it was. Never the root, /files/Uploads or /files/Public. Nothing you do deletes a file for good. Documented at https://docs.moonwalk.now/tools.html#files.

Edit a file

edit_file Changes

Replaces old with new in a text file, leaving the rest of it byte for byte. old must appear exactly once unless replace_all: enough of the lines around it make it unique. Nothing changes when the edit is refused, and the answer says why. write_file writes a whole file. Documented at https://docs.moonwalk.now/tools.html#files.

Move a file

move_file Changes Reaches outside

Moves or renames an entry. to is the whole new path. Never /files/Uploads or /files/Public itself, and never in or out of the trash.

Write a file

write_file Changes

Writes a whole text file, making or replacing it. The parent must exist, except under /files/.agent/memory/, whose folders are made.

Connections

Get a connection request

get_connection_request Reads

Returns how an ask was answered: pending or filled, and — once filled — the connection that was actually made, which may not be the name you asked for. 404 no_such_request once the person declined it, expired once the hour is up.

Get an account operation

get_account_operation Reads

Gets one operation of a linked account: its arguments in input_parameters, its output and its scopes.

List an account's operations

list_account_operations Reads

Lists the operations a linked account offers, narrowed by search. 409 not_an_account for a connection that was typed rather than clicked — only an account has a catalogue.

List connection requests

list_connection_requests Reads

Lists every ask in the base still waiting on the person — yours, another chat's, or one made over /api/mcp — with its name, kind, who asked, why, and when it runs out (expires_at). The list the Connections dot reads.

List connections

list_connections Reads

Lists every connection the base holds. The fields never come back out.

List linkable services

list_services Reads

Lists the services an account can be linked for, searched by name — the Connections screen's picker. request_connection's account slug comes from here. 503 not_configured means no account can be linked on this stack at all.

Ask for a connection

request_connection Adds

Asks the person for a credential you must never see. name and reason say which connection is wanted and why: secret, basic or hmac for a key they type, or account for a service they connect by clicking — then provider is the service's slug, like gmail. An API key, password or token must never pass through the conversation, asked for or pasted: this box is the only way one arrives. In the chat panel a box asks them above the composer and your turn waits: what comes back is their answer, {outcome, name, message?} — filled (steps bind to name), denied (the work goes on without it, and the conversation never asks for it instead), asked (they want to know why first, in message; a new ask follows the answer only if it is still needed) or expired. Anywhere else the answer is a URL for the person, and the work waits until they answer it there: get_connection_request says when they have. The name is a proposal: steps bind to the name the answer gives, not the one asked for. For a key, how_to_get is required: the path to it from where the person starts, as site > page > button, like platform.openai.com > API keys > Create new secret key. how_to_get_url, like https://platform.openai.com/api-keys, is the page, when it is known. It shows in the box where they type the key, so it is written for someone who has never done it. A path that is not certain says so, rather than inventing one. An account takes neither.

More

labels names the fields in the box, one per field in the kind's order: basic two (username, password), hmac two (key, secret), secret one, each up to 40 characters. They are for a pair that is not a login, or that the person would read as Username and Password of their own sign-in: a Google OAuth client is basic with ["Client ID", "Client secret"], an AWS key hmac with ["Access key ID", "Secret access key"]. A step still reads the kind's own names: username and password for basic, key and secret for hmac, secret. An account takes none.

Bind a connection to a step

bind_step_connection Changes

Binds a base connection to one declared key.

Delete a connection

delete_connection Changes

Deletes a connection. Refused while a step is bound to it.

Unbind a step's connection

unbind_step_connection Changes

Unbinds whatever is on one declared key.

Withdraw a connection request

withdraw_connection_request Changes

Takes a pending ask back, when the person asked you to drop it or you no longer need it. It removes any pending ask in the base, not only your own — list_connection_requests says who asked. Nothing is woken, not even the chat that asked: it learns from get_connection_request's 404, the way it learns of an expiry. 409 already_answered once filled.

Versions & trash

Get a version

get_version Reads

Returns one version, and what it changed against the version before it.

List the trash

list_trash Reads

Lists what one section has in its trash, newest first, each with when it goes for good (purge_at, 30 days after it was deleted). file lists a deleted folder and not what was in it, and each row carries the path it came from — which is what tells two files of one name apart. restore_board, restore_action, restore_table and restore_file bring one back, each by the id of a row here.

List versions

list_versions Reads

Lists a board's, a table's or an action's versions, newest first. One writer's writes inside ten minutes of each other are one version, and each row's actor_kind and via say whose: you, the person, or a run.

Preview the next undo

next_undo Reads

Returns what undo would take back, without taking it: the transaction, how many rows, and how many changes of each kind — drop or add for a column. undo takes the newest write of the member you act for — theirs in the browser as much as yours — so this is how to know which before it is taken. {"ok": true} when there is nothing to undo.

Revert to a version

revert_version Changes

Puts the resource back as an older version had it, as a new version — nothing is removed. A table goes back whole, other people's later writes included. An action's configs and bindings do not survive it, and it is refused while the action is active (409 locked).

Undo the last change

undo Changes

Takes back the newest transaction of the member you act for — one this session just made, or one they made in the browser; next_undo says which before you call it. A row write, or a column dropped or added: a dropped column comes back where it was, with its values. Cells another write has since changed are skipped and reported, never overwritten.

Moonwalk

List your bases

list_bases Reads

Lists the Moonwalk bases you can reach, as {id, name}, oldest first. Every other tool acts on one of them and takes its id as base_id, read_overview optionally. More than one base means the person's words may fit either.

Read the rules and what a base holds

read_overview Reads

Reads how a Moonwalk base works: its boards, tables, actions, files and the step SDK, and the rules no single tool states, which every other tool assumes. With base_id, also lists that base's boards, tables and actions.

Read where the person is

read_screen Reads

Reads which screen the person last had open in this base's web app: its section (boards, tables, actions, …), the id and name of what was open, and line, one sentence saying so. seconds_ago is how long since the tab reported it — it reports on moving and on coming back into view, so an old one most likely means the person has moved on to another window. {"screen": null} means this person has never had the base open.