session(1)

🌸 session(1) — the General Commands Manual one, bestie 🌸

okay so real talk: this is session(1) from the General Commands Manual and it's literally the entry point for starting or resuming your interactive chat sessions. buckle up 🎀

---

✨ NAME ✨

session — start or resume interactive chat sessions 💬

---

✨ SYNOPSIS ✨

session [-n|--name] [--session-id] [--path] [-r|--resume] [--fork]
[--edit] [--history] [--system] [--debug] [--max-tool-repetitions]
[--max-turns] [--container] [--with-extension]
[--with-streamable-http-extension] [--with-builtin] [--no-profile]
[--provider] [--model] [-h|--help] [subcommands]

---

✨ DESCRIPTION ✨

Start or resume interactive chat sessions. that's it, that's the vibe. you're either kicking off something new or sliding back into an old convo 👑🦋

---

✨ OPTIONS ✨

• -n, --name <NAME> — give your chat session a name 💖. and when you pair it with --resume, it'll resume that specific session, if it exists. cute and specific, we love that.
• --session-id <SESSION_ID> — straight-up hand it a session ID to resume. heads up tho: this one requires --resume. like it literally won't work without it 🙈
• --path <PATH> — legacy parameter for backward compatibility 🫶. it pulls the session ID out of a file path, like '/path/to/20250325_200615. jsonl' -> '20250325_200615'.
• -r, --resume — continue from a previous session ⭐. if you gave it --name or --session-id, it resumes that one. otherwise it just grabs the most recently used session. no thoughts, just vibes.
• --fork — create a brand new session by copying all the messages from a previous one 🧚. must be used with --resume. with --name or --session-id it forks that specific session; otherwise it forks the most recently used one. new session, same lore.
• --edit — opens the session's conversation in your editor ($VISUAL / $EDITOR / vi) so you can tweak it before resuming ✍️. and if you combine it with --fork, it creates a new session from the edited result. chef's kiss.
• --history — show previous messages when resuming a session 📜. context is everything, bestie.
• --system <TEXT> — drop in extra system instructions to customize the agent's behavior 🎀.
• --debug — when it's on, you get complete tool responses with no truncation and full paths 🔥. all the tea, unfiltered.
• --max-tool-repetitions <NUMBER> — caps how many times the same tool can be called consecutively with identical parameters 🌀. helps prevent infinite loops, which is honestly a public service.
• --max-turns <NUMBER> — limits how many turns (iterations) the agent can take without asking you for input to continue ⏳.
• --container <CONTAINER_ID> — runs extensions (stdio and built-in) inside the container you specify 📦. the extension must exist in the container, and for built-in extensions, goose must be installed inside the container too.
• --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 gets 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.
• --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 a timeout other than the default.
• --with-builtin <NAME> — add one or more builtin extensions bundled with goose by naming them, comma-separated 🎁.
• --no-profile — don't load your default extensions; only use the CLI-specified ones 🚫. minimal era.
• --provider <PROVIDER> — overrides the GOOSE_PROVIDER environment variable for this run 🔄. available providers include openai, anthropic, ollama, databricks, gemini-cli, claude-code, and others.
• --model <MODEL> — overrides the GOOSE_MODEL environment variable for this run 🧠. the model must be supported by the specified provider.
• -h, --help — print help (see a summary with '-h') 💜.

---

✨ SUBCOMMANDS ✨

• session-list(1) — list all available sessions 📋
• session-remove(1) — remove sessions. runs interactively if no ID, name, or regex is provided 🗑️
• session-export(1) — export a session 📤
• session-import(1) — import a session from JSON, a Claude Code / Codex / Pi .jsonl, or an encrypted Nostr share link 📥
• session-diagnostics(1) — 🩺
• session-help(1) — print this message or the help of the given subcommand(s) 🫶

---

✨ SEE ALSO ✨

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-run(1), goose-schedule(1), goose-serve(1), goose-skills(1), goose-term(1) — the whole friend group honestly 🌈💖

---

ngl bestie, that's the whole page. go start a session, resume a session, fork a session. live your truth 💅

okay byeee, this page is session from section 1 (session(1)), and that's a wrap 🎀✨🦋