Skip to content

rose-chat (CLI)

The rose-chat CLI tool enables rapid chatbot iteration. It calls the chatbot service directly (bypassing HTTP), maintains session state via Redis, and logs to files for easy inspection.

Installation

The CLI tool is available after activating the Poetry shell in the backend directory:

cd backend
poetry shell

Once in the Poetry shell, the rose-chat command is available.

Per-CLI secrets

Before invoking rose-chat or rose-eval, load dedicated CLI keys once in the same shell. From the repository root:

source backend/scripts/load-dev-secrets.sh

From backend/, use source scripts/load-dev-secrets.sh. Agent shell tool calls may start fresh shells; source the helper in each shell that will invoke a CLI. Re-sourcing refetches the keys; use it to refresh them after rotation. Subsequent CLI invocations in the same shell reuse the exported values.

OPENAI_API_KEY_CHAT and OPENAI_API_KEY_EVAL are standalone Secret Manager secrets, used for independent attribution and rate limits. Without an exported key, each CLI invocation fetches synchronously from Secret Manager. rose-chat warns about the missing shell key; rose-eval suppresses that reminder. Both warn on Secret Manager errors and retain the existing shared OPENAI_API_KEY as fallback. Add new dedicated keys to ROSE_DEV_SECRETS in the helper.

Before testing a client's chat: check knowledge freshness

Before testing, run rose-tenant find-latest <domain> to compare the client's data timestamps across test, staging, and production. This is a freshness estimate; failed checks or missing timestamps are inconclusive.

Use test when current. If staging/production is fresher, test lacks needed data, or freshness is unknown, explain the finding and ask the client/operator how to proceed before running chat. Reuse an existing decision for this task. Pass the chosen --env explicitly on every invocation.

A workspace-routed client (explicit_routing_enabled) has one corpus, served only in the environment of its last ingestion (sites.corpus_environment). In any other environment, workspace corpus is not ready in this environment is expected, not a missing ingestion: test in that environment.

Usage

rose-chat "message" --site <site-name> [OPTIONS]

Modes

Mode Usage Description
Single query rose-chat "message" --site foo.com Send one message, get a response
Continue rose-chat "message" --continue Continue the last conversation
Interactive rose-chat --interactive --site foo.com REPL mode for multi-turn testing
Info rose-chat --info Show last session info

Options

Option Short Default Description
message - - The message to send (positional, optional in interactive/info mode)
--site -s - Site name (required for new conversations)
--continue -c false Continue the last conversation
--session - - Use a specific session ID
--interactive -i false Enter interactive REPL mode
--info - false Show last session info
--env - development Environment: development, staging, production, test
--trace - false Enable Langfuse tracing
--add-to-dataset - - Add trace to dataset after chat (requires --trace). Defaults to main-dataset if no name given.
--dataset-type - e2e Type of dataset item to create: e2e, intent-classifier, skill-selector
--feature - - Override feature flags (repeatable, e.g. --feature some_flag=true)
--click-cta - - Simulate a CTA button click to trigger booking flow
--page-url - - Simulate the visitor's current page; drives page-targeted curated content, region skills and page-specific questions
--post-conversion - false Enable post-conversion qualification mode
--debug - false Enable debug logging to console
--eu-residency - false Route every chat model call to EU (EEA + Switzerland) deployments; fails if a use case has none

Examples

New conversation

rose-chat "What does Rose do?" --site mayday.fr

Continue the last conversation

rose-chat "Tell me more about pricing" --continue

Interactive REPL mode

rose-chat --interactive --site mayday.fr

In interactive mode, type messages at the prompt. Special commands:

  • quit / exit / q — End the session
  • new — Start a new session (same site)

Simulate CTA click (booking flow)

rose-chat "I want a demo" --site mayday.fr --click-cta 1
rose-chat "john@example.com" --continue

Post-conversion qualification mode

Test the post-conversion qualification questionnaire. This mode auto-sends a hidden welcome trigger, and the agent responds with the configured welcome message + first question. Suggested answers from the backend are displayed after each response.

# Start a post-conversion qualification flow (auto-sends welcome trigger)
rose-chat --post-conversion --site myreport.fr

# Answer subsequent questions (session remembers post-conversion mode)
rose-chat "51-200" --continue
rose-chat "Industrie automobile" --continue

The --post-conversion flag is persisted in session state, so --continue keeps the mode active without needing to re-specify it.

Output includes suggested answers when available:

🤖 Response:
Combien de collaborateurs compte votre entreprise ?

💡 Suggested answers: ['1-10', '11-50', '51-200', '201-500', '500+']

Enable Langfuse tracing

rose-chat "Can rose help with pricing?" --site userose.ai --trace

Add conversation to a dataset

# Add to default dataset (main-dataset)
rose-chat "What does your product do?" --site mayday.fr --trace --add-to-dataset

# Add to a named dataset
rose-chat "What does your product do?" --site mayday.fr --trace --add-to-dataset mayday.fr-v2

# Add as intent-classifier item
rose-chat "I need help" --site mayday.fr --trace --add-to-dataset intent-classifier --dataset-type intent-classifier

# Add as skill-selector item
rose-chat "Show me pricing" --site mayday.fr --trace --add-to-dataset skill-selector --dataset-type skill-selector

Session Management

rose-chat persists session state to backend/.chat_session.json. This enables --continue to resume the last conversation.

Session state includes:

  • session_id: Unique ID (cli_{site}_{timestamp}_{random})
  • site_name: The site for this session
  • created_at: When the session was created
  • turn_count: Number of messages exchanged
  • last_message_at: Timestamp of the last message

Session Lifecycle

  1. --site foo.com — Creates a new session
  2. --continue — Reuses the last session (same site and session ID)
  3. --session <id> --site foo.com — Uses a specific session ID
  4. In interactive mode, new — Creates a fresh session

--continue and --session do not remember the environment. Pass --env again on every turn: without it the CLI falls back to development and fails with Secret 'SUPABASE_SERVICE_ROLE_KEY' not found.

Scripted conversations in parallel

To replay several multi-turn conversations at once, use backend/scripts/rose-chat-convo.sh: run sends the turns of one conversation on one session and stores each turn's --debug output; show prints the transcript with the lookup-resolver line per turn.

source scripts/load-dev-secrets.sh
OUT=/tmp/convos-$(date +%s)
scripts/rose-chat-convo.sh run $OUT orisha.com staging bakery \
    "J'ai une boulangerie, quel logiciel ?" "Vous avez des clients boulangers ?" &
scripts/rose-chat-convo.sh run $OUT orisha.com staging btp \
    "On est une PME de BTP" "Plutôt le suivi terrain" &
wait
scripts/rose-chat-convo.sh show $OUT

Read node evidence (resolver, skill applier, profile extractor) from those per-turn files. Concurrent runs overwrite the shared backend/logs/chat-new_<timestamp>.log, so that file is not reliable for a batch; for a single question, a sequential --debug run is.

Dataset Population

rose-chat can populate Langfuse datasets for use with rose-eval. This replaces the old shell-script-based dataset creation.

Workflow

  1. Run a conversation with --trace to create a Langfuse trace
  2. Add --add-to-dataset <name> to extract the trace into a dataset item
  3. The tool waits for the trace to be available in Langfuse (retries up to 6 times)
  4. The trace is converted to evaluator-compatible format based on --dataset-type

Dataset Types

Type Format Used By
e2e (default) {"query": "..."} / {"response": "..."} E2EAPIEvaluator
intent-classifier Extracts intent from trace ClassificationEvaluator
skill-selector Extracts selected skills from trace MultiLabelEvaluator

Environment

By default, rose-chat runs in development environment, which:

  • Loads .env.development
  • Sets IX_IS_LOCAL=true

Prompts and skills always come from the repo files in your working tree, regardless of --env, so a run reflects an uncommitted edit immediately.

Use --env to override:

rose-chat "Hello" --site mayday.fr --env staging

Log Files

All sessions are logged to backend/logs/:

  • chat-{session_id}.log — Full log for each session
  • chat-latest.log — Symlink to the most recent log file

The log file path is displayed at the start of each run.

Troubleshooting retrieval initialization

ServerSelectionTimeoutError / mongodb.net:27017 timed out means the CLI cannot reach Mongo Atlas during RAG initialization. Atlas accepts only IPs on its project IP Access List: the cloud NAT IP (Terraform) plus entries operators add by hand. Local access is possible once your IP is listed. Confirm with nc -z -G 5 <shard host> 27017, then give the operator your public IP (curl -s -4 https://ifconfig.me) and ask them to allow it in Atlas before debugging further or falling back to a cloud preview. Neo4j Aura is reachable without an allowlist. A timeout alone does not establish that the ingested data is damaged.

On a workspace host, Processing query for site <host> (bot <key>) in the log shows which corpus answered. A site:<uuid> key is the workspace's own corpus. A bare domain key is the legacy tenant. Pass --page-url to preview a disabled workspace: it reaches the site:<uuid> corpus when that corpus is ready in the requested environment. A legacy key on a preview means the preview route is unavailable there (the database lacks the preview routing migration, or the corpus is not ready in that environment). Retrieval then often returns 0 documents.

Exit Codes

Code Meaning
0 Success
1 Error (query failure, missing arguments)
130 Cancelled by user (Ctrl+C)