From 6da23acba624d1f3728198e70005368b63e77fa6 Mon Sep 17 00:00:00 2001
From: Ebony Louis <55366651+EbonyLouis@users.noreply.github.com>
Date: Fri, 15 Nov 2024 21:05:24 -0500
Subject: [PATCH] docs: adding Managing Goose Sessions guide (#246)

---
 docs/guidance/managing-goose-sessions.md | 85 ++++++++++++++++++++++++
 mkdocs.yml                               |  1 +
 2 files changed, 86 insertions(+)
 create mode 100644 docs/guidance/managing-goose-sessions.md

diff --git a/docs/guidance/managing-goose-sessions.md b/docs/guidance/managing-goose-sessions.md
new file mode 100644
index 00000000..3f370b93
--- /dev/null
+++ b/docs/guidance/managing-goose-sessions.md
@@ -0,0 +1,85 @@
+# Managing Goose Sessions
+
+Goose sessions are your way to interact with Goose, providing a space to ask questions and prompt action. In this guide, we'll cover how to start, end, save, resume, and delete a session. 
+
+
+## Starting a Session 
+To start a new session, run the following command within your terminal: 
+
+```
+goose session start 
+```
+
+By default, Goose will provide a random string as the name of your session. If you'd like to provide a specific name, this is where you'd do so. For example to name your session 'react-migration', you would run:
+
+```
+goose session start react-migration
+```
+You'll know your session has started when your terminal looks similar to the following:
+
+```
+starting session | name: react-migration profile: default
+```
+
+!!! info
+    If this is your first session, Goose will prompt you for an API key to access an LLM (Large Language Model) of your choice. For more information on setting up your API key, see the [Getting Started Guide](https://block.github.io/goose/guidance/getting-started.html). Here is the list of [Goose-supported LLMs](https://block.github.io/goose/plugins/providers.html).
+
+## Exiting a Session
+
+To exit a session, hold down `Ctrl` + `C` to cancel and automatically save it. Alternatively, you can type `exit` to save and exit the session.
+
+
+Your session will be stored locally in a path similar to:
+
+```
+~/.config/goose/logs
+```
+
+This path is typically found in your `Users` folder.
+
+## Resuming a Session
+
+To resume your latest session, you can run the following command:
+
+```
+goose session resume
+```
+
+To resume a specific session, you can first check the sessions you currently have by running: 
+
+```
+goose session list 
+```
+
+This command will display a list of all saved sessions, showing a name, date, and time for each session. The output should look similar to the following: 
+
+```
+2024-11-12  14:12:28  managing-goose
+2024-11-12. 13:48:11  blog
+2024-11-12  13:27:21  react-migration
+2024-11-04  16:14:29  e6d7
+```
+
+To resume a specific session, run the following command: 
+
+```
+goose session resume react-migration
+```
+
+## Deleting Old Sessions
+
+Goose allows you to delete all previously saved sessions. However, it currently doesn't allow you to select specific sessions to delete. Be cautious when running this command as all sessions prior to the day the command was ran will be deleted. 
+
+To delete previously saved sessions, you can run the following command:
+
+```
+goose session clear
+```
+You can also decide how many sessions you want to keep, starting from the most recent. To keep 2 sessions you would run the following command: 
+
+```
+goose session clear --keep 2  
+```
+!!! info
+    Once a session is deleted it can not be retrieved.
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 48bad826..ac1018e9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -114,6 +114,7 @@ nav:
   - "Contributing": contributing.md
   - Guidance:
       - "Getting Started": guidance/getting-started.md
+      - "Managing Goose Sessions": guidance/managing-goose-sessions.md
       - "Quick Tips": guidance/tips.md
       - "Applications of Goose": guidance/applications.md
       - "Goose in Action": guidance/goose-in-action.md