Quickstart

10-Minute First Success

Use this page when you want a clean first run with minimum commands: install, setup, validate, ask, and chat.

1. Verify CLI is available

mosaic --version
mosaic --help
mosaic --project-state directory --ensure --check-writable

2. Configure one profile

export OPENAI_API_KEY=<your_key>

mosaic --project-state --profile default setup \
  --base-url https://api.openai.com \
  --api-key-env OPENAI_API_KEY \
  --model gpt-4o-mini

3. Validate provider/model connection

mosaic --project-state --profile default models list
mosaic --project-state --profile default health
mosaic --project-state --profile default status

4. Run your first ask/chat/tui

mosaic --project-state --profile default ask "hello"
mosaic --project-state --profile default chat
mosaic --project-state --profile default tui

Inside REPL, use /help, /status, and /exit.

5. Inspect sessions

mosaic --project-state session list
mosaic --project-state session show <session_id>

6. Optional: add local terminal channel

mosaic --project-state channels add --name local-terminal --kind terminal
mosaic --project-state channels list
mosaic --project-state channels send <channel_id> --text "quickstart ok"

Quick sanity checklist

• models list succeeds without network/config errors.
• ask returns a model response.
• chat and tui can start and exit normally.
• session list shows generated sessions.