Skip to main content
In this tutorial, you’ll pull an existing Metabind project to disk as files, edit one in your own editor, and send the change back: first as a draft you can inspect, then as a published release. By the end, you’ll have run the flat-file loop once and know which step is safe to repeat and which one goes live. Once the loop makes sense, the flat-file sync guide covers what this tutorial skips: conflicts, renames, and repairing local state.

​
Prerequisites

Before you start, make sure you have:
  • The Metabind CLI installed and signed in. See Install and Sign In. The CLI ships as a macOS binary through the Homebrew tap, with no Windows or Linux build and no npx form yet.
  • A project you can edit, saved as your active context with metabind use. Run metabind status to confirm which project you’re pointed at.
  • Any text editor. This tutorial edits a Markdown file, so you don’t need to know BindJS to finish it.

​
What You’ll Build

You’ll edit your project’s MCP instructions (the text Metabind surfaces to MCP clients), then publish that edit. Nothing here touches a component, so there’s no compile step and no way to break a running tool. The focus is the loop itself: Pull → edit → preview → push → publish. pull and the preview write nothing you can’t discard. push writes a draft. publish is the only step that changes what your live MCP app serves.

​
Pull Before You Push

push reads a baseline that pull records in .metabind/state.json to tell your edits apart from server-side changes. You have to pull a project before you can push it. Run push in a directory you never pulled, and it stops before doing anything:
The loop always starts with a pull.
1

Pull the Project Into a Folder

Write the project to a new directory. pull is read-only: it fetches the files and records the baseline push needs later.
You now have a folder of files: metabind.jsonc for project settings, mcp-instructions.md, components/ for BindJS source, tools/ for tool definitions, content/, and a CLI-owned .metabind/ directory holding the baseline. Secret values are never written, only their names. For the full layout, see the flat-file sync guide.
2

Change One File

Open mcp-instructions.md in the folder you pulled and add a line:
Save the file. This is an ordinary edit, detected by content rather than timestamp, so a file you didn’t touch never registers as changed.
3

Preview What Would Change

Before writing anything back, preview the change. push --plan reports the changelist and exits without touching the server.
You should see your project settings marked as updated and everything else unchanged. --plan never writes, so you can rerun it as often as needed.
4

Push the Change as a Draft

Apply the edit. push writes to the server, but only ever as a draft, so nothing your published MCP app serves changes yet.
If someone edited the same entity in Studio since you pulled, push refuses the whole batch rather than merging, so follow Resolving Conflicts to reconcile it. It also stops before sending anything if an edit looks like it holds a secret value, so keep secrets in project secret bindings and reference them by name instead.
5

Publish the Release

Promote the draft to published. This is the step that changes what your live app serves: the same release action as publishing from Studio.
If you only wanted to try the loop, stop before this step. A draft stays untouched until you publish it or replace it with a fresh pull.

​
Verify It Works

Run the preview again from the same folder:
With your edit pushed and nothing else changed, it should report no changes to make. You can also open the project to see the published instructions:

​
What You’ve Built

You’ve run the full flat-file loop once: you pulled a project to disk, edited it in your own editor, previewed the change, pushed it as a draft, and published it. Two rules keep the loop safe: pull establishes the baseline push depends on, and push only ever writes drafts, so publish is the single deliberate step that goes live.

​
Next Steps

Flat-File Sync

The full workflow: project layout, conflicts, renames, and repairing local state.

CI Publish Lane

Run this same loop from GitHub Actions, without storing a credential.

Workflow Map

Every CLI command family, grouped by the job it does.