Skip to main content
The conversation command group (also accessible as session) manages conversation history, allowing you to list, resume, export, and manipulate past AI conversations.

​
Usage

forge conversation [SUBCOMMAND] [OPTIONS]
forge session [SUBCOMMAND] [OPTIONS]  # Alias

​
Subcommands

​
list

List all conversation history. 
forge conversation list
​
--porcelain
boolean
default:"false"
Output in machine-readable format.
forge conversation list --porcelain

​
new

Create a new conversation. 
forge conversation new

​
dump

Export a conversation as JSON or HTML. 
forge conversation dump <ID> [OPTIONS]
​
id
uuid
required
Conversation ID to export.
forge conversation dump 550e8400-e29b-41d4-a716-446655440000
​
--html
boolean
default:"false"
Export as HTML instead of JSON.
forge conversation dump 550e8400-e29b-41d4-a716-446655440000 --html

​
compact

Compact a conversation to reduce token usage by removing redundant context. 
forge conversation compact <ID>
​
id
uuid
required
Conversation ID to compact.
forge conversation compact 550e8400-e29b-41d4-a716-446655440000

​
retry

Retry the last command without modifying context. 
forge conversation retry <ID>
​
id
uuid
required
Conversation ID to retry.
forge conversation retry 550e8400-e29b-41d4-a716-446655440000

​
resume

Resume a conversation in interactive mode. 
forge conversation resume <ID>
​
id
uuid
required
Conversation ID to resume.
forge conversation resume 550e8400-e29b-41d4-a716-446655440000

​
show

Show the last assistant message from a conversation. 
forge conversation show <ID> [OPTIONS]
​
id
uuid
required
Conversation ID.
forge conversation show 550e8400-e29b-41d4-a716-446655440000
​
--md
boolean
default:"false"
Print raw markdown without rendering.
forge conversation show 550e8400-e29b-41d4-a716-446655440000 --md

​
info

Show conversation details. 
forge conversation info <ID>
​
id
uuid
required
Conversation ID.
forge conversation info 550e8400-e29b-41d4-a716-446655440000

​
stats

Show conversation statistics. 
forge conversation stats <ID> [OPTIONS]
​
id
uuid
required
Conversation ID.
forge conversation stats 550e8400-e29b-41d4-a716-446655440000
​
--porcelain
boolean
default:"false"
Output in machine-readable format.
forge conversation stats 550e8400-e29b-41d4-a716-446655440000 --porcelain

​
clone

Clone a conversation with a new ID. 
forge conversation clone <ID> [OPTIONS]
​
id
uuid
required
Conversation ID to clone.
forge conversation clone 550e8400-e29b-41d4-a716-446655440000
​
--porcelain
boolean
default:"false"
Output in machine-readable format.
forge conversation clone 550e8400-e29b-41d4-a716-446655440000 --porcelain

​
delete

Delete a conversation permanently. 
forge conversation delete <ID>
​
id
string
required
Conversation ID to delete.
forge conversation delete 550e8400-e29b-41d4-a716-446655440000

​
Examples

​
List All Conversations

forge conversation list
Example output: 
Conversation History:

ID                                     Date        Messages  Agent
550e8400-e29b-41d4-a716-446655440000  2024-01-15  42        sage
660e9500-f39c-52e5-b827-557766551111  2024-01-14  18        muse
770fa611-g49d-63f6-c938-668877662222  2024-01-13  27        forge

​
Resume a Conversation

forge conversation resume 550e8400-e29b-41d4-a716-446655440000
Alternatively, use the shorthand: 
forge --cid 550e8400-e29b-41d4-a716-446655440000

​
Export as JSON

forge conversation dump 550e8400-e29b-41d4-a716-446655440000 > conversation.json

​
Export as HTML

forge conversation dump 550e8400-e29b-41d4-a716-446655440000 --html > conversation.html

​
Show Last Message

forge conversation show 550e8400-e29b-41d4-a716-446655440000
Get raw markdown: 
forge conversation show 550e8400-e29b-41d4-a716-446655440000 --md

​
View Statistics

forge conversation stats 550e8400-e29b-41d4-a716-446655440000
Example output: 
Conversation Statistics:

  Messages:        42
  User messages:   21
  AI messages:     21
  Total tokens:    125,430
  Estimated cost:  $0.87
  Duration:        45 minutes
  Agent:           sage
  Model:           anthropic/claude-sonnet-4

​
Clone a Conversation

forge conversation clone 550e8400-e29b-41d4-a716-446655440000
Example output: 
✓ Conversation cloned
  New ID: 770fa611-g49d-63f6-c938-668877662222

​
Compact a Conversation

Reduce token usage by removing redundant context: 
forge conversation compact 550e8400-e29b-41d4-a716-446655440000
Example output: 
✓ Conversation compacted
  Removed 35,420 tokens
  New size: 90,010 tokens

​
Delete a Conversation

forge conversation delete 550e8400-e29b-41d4-a716-446655440000
Example output: 
✓ Conversation deleted

​
Alternative Commands

You can use session as an alias: 
forge session list
forge session resume 550e8400-e29b-41d4-a716-446655440000
forge session show 550e8400-e29b-41d4-a716-446655440000
You can also use the list command: 
forge list conversation
forge list session

​
Machine-Readable Output

Many conversation commands support --porcelain for scripting: 
forge conversation list --porcelain | jq '.conversations[] | select(.agent == "sage")'
forge conversation stats 550e8400-e29b-41d4-a716-446655440000 --porcelain

​
Storage Location

Conversations are stored in: 
~/.local/share/forge/conversations/
Each conversation is stored as a JSON file named with its UUID.
  • forge --cid <ID> - Resume a conversation
  • forge info --cid <ID> - Show info for a specific conversation
  • forge - Start a new conversation

​
Notes

  • Conversation IDs are UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000)
  • Use compact to reduce token usage in long conversations
  • Exported HTML includes syntax highlighting and formatting
  • clone creates an independent copy with a new ID
  • retry is useful when the AI response was incomplete or incorrect

Build docs developers (and LLMs) love

Get started for freeTalk to us