run(1)

💅 run — like, the manual page, but make it make sense 🦋

okay so bestie, you're in the run(1) page of the General Commands Manual and honestly? this is the one you'll actually use. it executes commands from an instruction file or from stdin, and it's lowkey the main character of the whole goose family. let's get into it ✨

---

🌸 NAME 🌸

run — execute commands from an instruction file or stdin, no cap

---

🎀 SYNOPSIS 🎀

run [-i|--instructions] [-t|--text] [--recipe] [--system] [--params]
[--sub-recipe] [--explain] [--render-recipe] [-n|--name] [--session-id]
[--path] [-s|--interactive] [--no-session] [-r|--resume] [--stats]
[--debug] [--max-tool-repetitions] [--max-turns] [--container]
[--with-extension] [--with-streamable-http-extension] [--with-builtin]
[--no-profile] [-q|--quiet] [--output-format] [--provider] [--model]
[-h|--help]

yeah it's a long one. she's got range 💅

---

🦋 DESCRIPTION 🦋

okay so the whole vibe: run executes commands from an instruction file or stdin. that's it, that's the tweet. everything else below is just you customizing the experience ✨

---

💖 OPTIONS 💖

bestie there are SO many. buckle up, we're going through all of them, no skipping 🫶

• -i, --instructions <FILE> — path to the instruction file that's holding your commands. honestly iconic. and yes, you can use - for stdin if that's your thing 💜
• -t, --text <TEXT> — just paste the input text containing commands for goose right here. use this in lieu of the instructions argument. inline slay.
• --recipe <RECIPE_NAME or FULL_PATH_TO_RECIPE_FILE> — a recipe name to get the recipe file, or the full path of the recipe file that defines a custom agent configuration. and like, use --explain if you wanna peek at the recipe's title, description, and parameters first. very demure, very mindful 👑
• --system <TEXT> — drop in extra system instructions to customize the agent's behavior. main character energy for your agent fr
• --params <KEY=VALUE> — key-value parameters to pass to the recipe file. can be specified multiple times, so go off 🎀
• --sub-recipe <RECIPE> — specify sub-recipes to include alongside the main recipe. it can be:
  • recipe names from GitHub (if GOOSE_RECIPE_GITHUB_REPO is configured)
  • local file paths to YAML files

can be specified multiple times to include multiple sub-recipes. the way that she stacks 🌈

• --explain — show the recipe title, description, and parameters. like a lil preview, iykyk
• --render-recipe — print the rendered recipe instead of running it. look but don't touch vibes 🙈
• -n, --name <NAME> — pick a name for your chat session. and when you use it with --resume, it'll resume that specific session if it exists. she remembers you 💖
• --session-id <SESSION_ID> — specify a session ID to resume. requires --resume, so don't forget that part bestie 😭
• --path <PATH> — legacy parameter for backward compatibility. it extracts the session ID from the file path (e.g., '/path/to/20250325_200615. jsonl' -> '20250325_200615'). old but still serving 🫶
• -s, --interactive — keep going in interactive mode after processing the initial input. she's not done talking ✨
• --no-session — execute commands without creating or using a session file. useful for automated runs. no strings attached 💀
• -r, --resume — continue from a previous run, maintaining the execution state and context. we love continuity 👑
• --stats — print generation statistics after the run completes. numbers, bestie, numbers 🍓
• --debug — when enabled, shows complete tool responses without truncation AND full paths. the unfiltered truth 🔥
• --max-tool-repetitions <NUMBER> — set a limit on how many times the same tool can be called consecutively with identical parameters. helps prevent infinite loops, which, thank god 😭
• --max-turns <NUMBER> — set a limit on how many turns (iterations) the agent can take without asking for user input to continue. boundaries are self-care 💅
• --container <CONTAINER_ID> — run extensions (stdio and built-in) inside the specified container. the extension must exist in the container. for built-in extensions, goose must be installed inside the container. putting her in a box, respectfully 🎀
• --with-extension <COMMAND> — add stdio extensions from full commands with environment variables. can be specified multiple times. format:

'[name:]ENV1=val1 ENV2=val2 command args...'

without the optional name, the extension is named after the command — which is the launcher for anything started through one ('npx', 'python', 'uvx', ...). extensions that would end up sharing a name are instead named after their full command line. she's thorough ✨

• --with-streamable-http-extension <URL> — add streamable HTTP extensions from a URL. can be specified multiple times. format: 'url...' or 'url... timeout=100' to set up a timeout other than default 🌈
• --with-builtin <NAME> — add one or more builtin extensions that are bundled with goose by specifying their names, comma-separated. bundled = free real estate 🦋
• --no-profile — don't load your default extensions, only use CLI-specified extensions. strict queen behavior 👑
• -q, --quiet — quiet mode. suppress non-response output, printing only the model response to stdout. shhh 🤫
• --output-format <FORMAT> [default: text] — output format (text, json, stream-json). possible values:
  • text
  • json
  • stream-json

pick your fighter 💜

• --provider <PROVIDER> — override the GOOSE_PROVIDER environment variable for this run. available providers include openai, anthropic, ollama, databricks, gemini-cli, claude-code, and others. so many options, so little time 🌸
• --model <MODEL> — override the GOOSE_MODEL environment variable for this run. the model must be supported by the specified provider, no cap ⭐
• -h, --help — print help (see a summary with -h). the classic 🫶

---

🔥 SEE ALSO 🔥

literally the whole friend group: goose(1), goose-acp(1), goose-completion(1), goose-configure(1), goose-doctor(1), goose-gateway(1), goose-info(1), goose-mcp(1), goose-plugin(1), goose-recipe(1), goose-review(1), goose-schedule(1), goose-serve(1), goose-session(1), goose-skills(1), goose-term(1). go say hi 💖

---

ngl, if you're about to run something automated, remember that --no-session exists and --max-tool-repetitions is your bestie against infinite loops. you're welcome 😭

---

and that's the page, bestie 🎀 this one's from the General Commands Manual, run(1), and the footer says run on both sides — dated run(1), source and version exactly as she came. mwah 💋✨