> ## Documentation Index > Fetch the complete documentation index at: https://vvennela-ftl-18-95.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Interactive Shell > Use the FTL interactive shell for multi-turn agent conversations The FTL interactive shell provides a persistent session where you can issue follow-up instructions to the agent without cold-booting between tasks. ## Starting the Shell Launch the interactive shell from your project directory: ```bash theme={null} ftl ``` > [!NOTE] > > You must run `ftl init` in your project before using the interactive shell. ## Shell Prompt States The shell has two prompt states: > [tab] Idle > > ```bash theme={null} > ftl> > ``` > > No active session. Type a task to start a new session. > [tab] Active Session > > ```bash theme={null} > ftl[active]> > ``` > > Session is active. Follow-up instructions continue the same agent conversation. ## Basic Workflow **1. Start Shell** ```bash theme={null} ftl ``` Output: ``` FTL Shell Agent: claude-code | Tester: claude-haiku-4-5-20251001 Type a task to start. Commands: test, diff, merge, reject, list, restore , exit ftl> ``` **2. Issue Task** Type a task description to start a new session: ```bash theme={null} ftl> build a login page with email and password ``` FTL snapshots your project, boots the sandbox, and runs the agent. **3. Review Changes** Once the agent completes, the session becomes active: ```bash theme={null} Session active. Commands: test, diff, merge, reject Or type a follow-up instruction for the agent. ftl[active]> ``` **4. Follow-up Instructions** Continue the conversation with follow-up tasks: ```bash theme={null} ftl[active]> add form validation ``` The agent continues in the same container with full context. **5. Merge or Reject** When satisfied, merge the changes: ```bash theme={null} ftl[active]> merge ``` Or reject to discard all changes: ```bash theme={null} ftl[active]> reject ``` ## Session Commands These commands are available when a session is active: ### diff Show all changes since the snapshot: ```bash theme={null} ftl[active]> diff ``` Displays a unified diff of all modified files. ### test Re-run tests manually: ```bash theme={null} ftl[active]> test ``` Executes the adversarial tests generated for this session. ### merge Review and merge changes to your project: ```bash theme={null} ftl[active]> merge ``` FTL displays the diff and prompts for approval: ```bash Interactive Review theme={null} ftl[active]> merge [Diff displayed] Approve changes? a — approve and merge r — reject and discard Any other input — ask the model a question > ``` ```bash Approve theme={null} > a [green]Changes merged to project.[/green] ftl> ``` ```bash Reject theme={null} > r [red]Changes discarded.[/red] ftl> ``` ```bash Ask Question theme={null} > does this handle null inputs? [Model responds with analysis] Approve changes? > ``` ### reject Discard all changes and end the session: ```bash theme={null} ftl[active]> reject ``` The sandbox state is discarded and the prompt returns to `ftl>`. ## Snapshot Commands These commands are available at any time: ### list List snapshots for the current project: ```bash theme={null} ftl> list ``` Output: ``` abc123 /home/user/myproject def456 /home/user/myproject ghi789 /home/user/myproject ``` ### list all List snapshots for all projects: ```bash theme={null} ftl> list all ``` ### restore Restore a previous snapshot: ```bash theme={null} ftl> restore abc123 ``` FTL prompts for confirmation before restoring: ``` Restore snapshot abc123? Are you sure? (y/n) > ``` ## Example Session Here's a complete interactive session: ```bash theme={null} $ ftl FTL Shell Agent: claude-code | Tester: claude-haiku-4-5-20251001 ftl> create a Stripe payment module [Snapshotting...] [Booting sandbox...] [Running agent...] [Agent completes] Session active. Commands: test, diff, merge, reject ftl[active]> add error handling for failed payments [Agent continues...] [Agent completes] ftl[active]> diff [Unified diff displayed] ftl[active]> test [Tests run] All tests passed. ftl[active]> merge [Diff displayed] Approve changes? a — approve and merge r — reject and discard Any other input — ask the model a question > does this handle webhook signature verification? Yes, the implementation includes webhook signature verification using Stripe's constructEvent() method with the webhook secret... Approve changes? > a Changes merged to project. ftl> exit Goodbye. ``` ## Session Lifecycle ```mermaid theme={null} stateDiagram-v2 [*] --> Idle: ftl Idle --> Active: Type task Active --> Active: Follow-up instruction Active --> Active: diff/test Active --> Idle: merge Active --> Idle: reject Idle --> [*]: exit Active --> [*]: exit (auto-reject) ``` ### Persistent Container The shell uses a persistent container per project: | Location | Behavior | Notes | | - | - | - | | `/workspace/` | Wiped and restored from snapshot on each task | Project files | | `/home/ftl/.local/` | Persists across tasks | `pip install` packages | | `/home/ftl/.claude/` | Persists across tasks | Conversation history | | Global node\_modules | Persists across tasks | `npm install -g` | ### Follow-up Context When you issue a follow-up instruction: **1. Same Container** The agent runs in the same container with all previous context **2. Same Conversation** Conversation history in `/home/ftl/.claude/` is preserved **3. No Snapshot** FTL does not create a new snapshot for follow-ups **4. Cumulative Diff** The diff shows all changes since the original snapshot ## Exiting the Shell Exit the shell with any of these: ```bash exit command theme={null} ftl> exit Goodbye. ``` ```bash quit command theme={null} ftl> quit Goodbye. ``` ```bash Ctrl+C theme={null} ftl> ^C Goodbye. ``` ```bash Ctrl+D (EOF) theme={null} ftl> ^D Goodbye. ``` > [!WARNING] > > If you exit with an active session, FTL automatically rejects all changes to prevent accidental merges. ## Shell Implementation The shell is implemented in `ftl/cli.py`: ```python ftl/cli.py theme={null} def shell(): """Interactive FTL shell with session support.""" console = Console() if not find_config(): console.print("[red]No .ftlconfig found. Run 'ftl init' first.[/red]") raise SystemExit(1) config = load_config() console.print("[bold]FTL Shell[/bold]") console.print(f"[dim]Agent: {config['agent']} | Tester: {config['tester']}[/dim]") console.print("[dim]Type a task to start. Commands: test, diff, merge, reject, list, restore , exit[/dim]\n") from ftl.snapshot import create_snapshot_store snapshot_store = create_snapshot_store(config) session = None while True: prompt = "ftl[active]> " if session and session.is_active else "ftl> " try: user_input = input(prompt).strip() except (KeyboardInterrupt, EOFError): console.print("\n[dim]Goodbye.[/dim]") if session and session.is_active: session.reject() break if not user_input: continue if user_input in ("exit", "quit"): if session and session.is_active: session.reject() break # [Command handling logic] ``` ## Tips > [accordion] Use follow-ups for refinement > > Instead of crafting perfect initial instructions, start with a basic task and refine with follow-ups: > > ```bash theme={null} > ftl> create a login form > ftl[active]> add client-side validation > ftl[active]> add password strength indicator > ftl[active]> add remember me checkbox > ``` > [accordion] Check diffs before merging > > Always run `diff` before `merge` to review all accumulated changes: > > ```bash theme={null} > ftl[active]> diff > ftl[active]> merge > ``` > [accordion] Use list to track snapshots > > Run `list` to see all snapshots for the current project: > > ```bash theme={null} > ftl> list > ``` > > Use `restore ` if you need to revert to a previous state. > [accordion] Test early and often > > Run tests manually after each follow-up to catch issues early: > > ```bash theme={null} > ftl[active]> add error handling > ftl[active]> test > ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.