Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use these loops when work needs to be repeated, reviewed, or handed off. Each one starts from observable project state, validates before writes, and ends with evidence from the runtime.

​
Start From Project State

Before changing anything, establish the operating target.
  1. Run metabind status.
  2. Confirm the active account, organization, and project.
  3. Save the intended project scope with metabind use if the current context is incomplete or wrong.
  4. Re-run metabind status before making changes.
Do not infer the project from the repository path. CLI context is saved for the OS user unless the process uses an isolated config directory.

​
Build a UI Tool

The UI tool loop starts with a BindJS component module and ends with a project tool:
  1. Read the relevant BindJS reference with metabind bindjs.
  2. Write component source, or read the current component before editing an existing one.
  3. Validate the module with metabind validate.
  4. Create or update the component with metabind component.
  5. Create or update the MCP tool with metabind tool.
  6. Publish when the draft state is ready.
  7. Compile or snapshot the published view with representative content.
A compact UI component uses a default defineComponent export and includes previews for Composer surfaces: 
export default defineComponent({
  metadata: {
    title: "Pricing Card",
    description: "Displays a plan name, price, and feature summary"
  },
  properties: {
    plan: { type: "string" },
    price: { type: "string" },
    features: { type: "array", valueType: { type: "string" } }
  },
  body: (props) =>
    VStack({ spacing: 12 }, [
      Text(props.plan).font("title"),
      Text(props.price).font("largeTitle").bold(),
      Text(props.features.map((feature) => `- ${feature}`).join("\n")).font("body")
    ]).padding(24),
  previews: [
    Self({
      plan: "Pro",
      price: "$99",
      features: ["Priority support", "Team seats"]
    }).previewName("Default"),
    Self({
      plan: "Enterprise",
      price: "Custom",
      features: ["SAML SSO", "Dedicated support", "Security review"]
    }).previewName("Enterprise")
  ]
});

​
Build a Data Tool

Data tools use server-side defineDataSource modules. They are a good fit when a tool needs to compute data, call an external API, or return structured output before a UI renders it. 
export default defineDataSource({
  metadata: {
    title: "Pricing Search",
    description: "Search pricing plans by query"
  },
  properties: {
    query: { type: "string", description: "Search query" }
  },
  output: {
    summary: { type: "string", description: "Human-readable result" }
  },
  annotations: {
    readOnlyHint: true,
    openWorldHint: false
  },
  handler: async (props, env) => {
    const plans = [
      { name: "Starter", price: "$19", tags: ["trial", "solo"] },
      { name: "Pro", price: "$99", tags: ["team", "priority"] },
      { name: "Enterprise", price: "Custom", tags: ["sso", "security"] }
    ];

    const query = props.query.toLowerCase();
    const match =
      plans.find((plan) => plan.name.toLowerCase() === query) ??
      plans.find((plan) => plan.tags.some((tag) => tag.includes(query))) ??
      plans[0];

    const catalog = env.secrets.PRICING_API_KEY ? "private catalog" : "public catalog";
    return { summary: `${match.name}: ${match.price} from the ${catalog}.` };
  }
});
The data tool loop:
  1. Validate the source module.
  2. Create the data tool atomically with metabind data-tool.
  3. Bind referenced secrets with metabind env.
  4. Allow external domains when the handler calls outside services.
  5. Publish when the draft state is ready.
  6. Execute the published tool with representative input.
Data-source handlers read secrets from env.secrets, not from process environment variables.

​
Publish

Publishing is a release step. It freezes draft state into a package version and updates the runtime pins for changed tools. Before publishing, confirm the release is ready:
  • confirm the active project with metabind status
  • run metabind doctor
  • inspect changed components and tools
After publishing, compile or snapshot UI tools with representative content, execute data tools with representative input, and report the resulting state and surfaces to test, such as Composer and the MCP endpoint.

​
Roll Back

Rollback moves tool pins back to a previous published package version. It does not delete the newer package. Treat rollback as an operational change:
  1. Inspect the current tool and package state.
  2. Choose the package version that should run.
  3. Roll back only the intended tools.
  4. Compile or execute the affected tools against representative input.
  5. Use persisted rollback when the target component source should become the next package version.
  6. Run metabind doctor afterward.
After rollback, the project can intentionally serve older pins. Use upgrade when the goal is to move those pins forward again. Use persisted rollback when the goal is to make the older behavior the new latest package. Use component-level history when the goal is to revert one component’s source. Use project rollback when the goal is to move runtime tool pins.

​
Manage Secrets

Data tools reference secrets by key through env.secrets. The CLI stores values and binds them to the data tools whose handlers reference those keys. Never place secret values in markdown summaries, issue comments, or final responses. Use the secure input path from metabind env when setting values so secrets do not appear in command history. Use metabind env list to inspect which keys exist and which tools reference them. Values are intentionally not returned.

​
Hand Off to an MCP Host

MCP hosts need two project values:
  • the MCP endpoint from metabind url
  • a project API key from metabind api-key
The plaintext API key is only available when it is created. Store it in the MCP host configuration immediately, then use API key listings only for metadata and audits.

​
Completion Checklist

Before reporting work complete, be able to answer:
  • Which org and project did it operate on?
  • Which components, tools, content rows, secrets, or API keys changed?
  • Was the project published, left in draft, rolled back, or only inspected?
  • What did metabind doctor report after the changes?
  • Which MCP endpoint or app surface should the human test?
If a command error was confusing or a workflow needed a workaround, file metabind feedback from the same shell so the CLI can attach useful context.