FamilyPlate

Agent Access

Connect trusted agents to FamilyPlate

FamilyPlate lets users connect Codex, Claude, Cursor, and terminal agents with scoped CLI access. Agents can read household food context and, when explicitly allowed, help manage grocery, pantry, meal plan, and saved recipe items without using the user's password or browser session.

Sign In Model

Agents should not ask for or automate a user's FamilyPlate password. The user signs in, opens Settings, creates an Agent Access connection, and gives the agent the one-time terminal command. After that, the agent uses the CLI token instead of a browser session.

User Settings

Signed-in users create and revoke Agent Access connections here.

Agent Setup

Public setup guide agents can read before asking the user for access.

Setup Flow

  1. 1. The user signs in at FamilyPlate and opens Settings.
  2. 2. The user creates an Agent Access connection.
  3. 3. FamilyPlate shows a one-time token command.
  4. 4. The agent runs the command locally and checks readiness.
  5. 5. The user revokes the connection in Settings when finished.
npx @familyplate/cli@latest instructions
npx @familyplate/cli@latest connect --api-url https://effervescent-gecko-133.convex.site --token fp_agent_...
npx @familyplate/cli@latest doctor --pretty

Safe Read Commands

Read-only connections can inspect pantry, grocery, meal plan, and cookbook data for the connected household.

familyplate pantry list --pretty
familyplate grocery list --pretty
familyplate plan list --pretty
familyplate recipes list --pretty

Confirmed Writes

Writes require optional write scopes and explicit confirmation. Agents should use dry runs first when the target item is ambiguous.

familyplate grocery add "olive oil" --quantity 1 --unit bottle --category Pantry --dry-run --pretty
familyplate grocery add "olive oil" --quantity 1 --unit bottle --category Pantry --confirm --pretty
familyplate grocery update "olive oil" --quantity 2 --category Condiments --dry-run --pretty
familyplate grocery check "Tomatoes" --dry-run --pretty
familyplate grocery check "Tomatoes" --confirm --pretty
familyplate pantry add "Chicken thighs" --quantity 2 --unit lb --category Meat --location fridge --dry-run --pretty
familyplate pantry update --item-id <pantry_item_id> --quantity 1 --dry-run --pretty
familyplate pantry remove --item-id <pantry_item_id> --dry-run --pretty
familyplate plan add --recipe-id <recipe_id> --date 2026-06-15 --dry-run --pretty
familyplate plan remove --meal-id <planned_meal_id> --dry-run --pretty
familyplate recipes create --input '{"title":"Black Bean Tacos","ingredients":[{"name":"Black beans","quantity":1,"unit":"can"}],"instructions":["Warm beans and tortillas."],"effortLevel":"easy","estimatedTime":15,"servings":4}' --dry-run --pretty

Available Tools

whoami

Confirm the connected FamilyPlate profile and household.

listPantry

Read pantry, fridge, and freezer items.

listGroceryList

Read the household grocery list.

listMealPlan

Read the active 7-night dinner plan.

listSavedRecipes

Read saved cookbook recipes.

addGroceryItem

Add one grocery item with write scope and confirmation.

updateGroceryItem

Update grocery quantity, unit, category, or checked state.

checkGroceryItem

Check off one grocery item with write scope and confirmation.

addPantryItem

Add one pantry, fridge, or freezer item.

updatePantryItem

Update a pantry item by id.

removePantryItem

Remove a pantry item by id.

addMealToPlan

Add or replace a planned dinner.

removeMealFromPlan

Remove a planned dinner.

createSavedRecipe

Create a saved cookbook recipe.

Agent-Readable Resources

Agent Manifest

Machine-readable setup, commands, scopes, and safety rules.

CLI Skill

Markdown instructions for agents learning how to connect.

Skills Index

Discovery index for FamilyPlate agent skills.

Tool Registry

Live JSON list of tools exposed by the agent API.

Safety Model

  • Agent tokens are separate from household invite codes.
  • Agents should never ask for the user's FamilyPlate password.
  • Tokens are shown once, stored hashed, and revocable from Settings.
  • Users can choose 1 hour, 24 hours, 7 days, or no expiration.
  • Each request checks the token, household, profile, and required scope.
  • Agents should not provide diagnosis, treatment, or medical nutrition advice.
FamilyPlate Agent Setup