CLI Reference — igor

igor chat [OPTIONS]

Option	Default	Description
--kb-dir PATH	./kb	Path to the knowledge base directory. Override if you've moved or customised the KB files.
--db-path PATH	./.igor/igor.db	Path to the SQLite session database. Use different paths to maintain separate session histories (e.g. for different clients).
--client-id ID	none	Tag this session with a client identifier. Used to group sessions by person when reviewing transcripts. Does not affect session behaviour.
--instant	off	Disable the character-by-character typing animation. All responses print immediately. Equivalent to setting IGOR_INSTANT_OUTPUT=1.
--voice	off	Enable voice output (text-to-speech) and voice input (Whisper transcription). Requires pip install -e .[voice].
--browser	off	Render the session in a browser tab instead of the terminal. Requires pip install -e .[browser] and playwright install chromium.
--port PORT	7890	Local port for browser delivery mode. Use if 7890 is taken.
--yes	off	Auto-accept the consent prompt. For automated testing only — never use with a real person as the subject.
--model MODEL	claude-sonnet-4-5	Override the executor model. Any Anthropic model name is valid. Lighter models (Haiku) are faster and cheaper; Opus produces richer prose but costs more.

Example — basic session

$ igor chat

Igor Hypnosis v0.4.1
Knowledge base: 22 modules, 47 techniques loaded.

Hello. I'm Igor — a conversational hypnotherapy guide built on the
principles taught in the Professional Hypnotherapy 3.0 course.

Before we begin, I want to be clear about what this is: a guided
self-development session using hypnotic language and techniques.
You are in control at all times. You can stop by typing "stop"
at any point, and I will bring the session to a calm close.

Do you consent to begin? (yes/no): yes

Good. Let's start. What's something you'd like to feel differently
about, or a pattern you'd like to shift?

> I keep procrastinating on things that matter to me.

Thank you. And when you imagine the version of you that doesn't
procrastinate — what does that feel like? What's the quality of
that state?

> Focused. Clear. Like things just flow.

[Session continues...]

Example — instant output with custom KB and client tag

$ igor chat --instant --client-id alice --kb-dir ~/my-custom-kb

Example — browser delivery on port 9000

$ igor chat --browser --port 9000
Starting browser session on http://localhost:9000 ...
Opening Chromium ...

igor mbl <PROBLEM> <RESOURCE> [OPTIONS]

PROBLEM and RESOURCE are positional string arguments. Phrase them as verb phrases or gerunds for the most natural output ("feeling anxious" rather than "anxiety").

Option	Default	Description
--all	off	Show all 28 generated questions instead of the default curated set of 7 (one per 7W). Useful when you want to browse the full matrix.
--kb-dir PATH	./kb	Path to the KB directory. The MBL formula templates are loaded from here.
--format FORMAT	plain	Output format. Options: plain (one question per line), json (array), numbered (numbered list).

Example — default output (7 questions)

$ igor mbl "feeling anxious" "feeling calm"

Who is it that is not feeling anxious, that's feeling calm?
What is it that's not feeling anxious, that's feeling calm?
When is it that you're not feeling anxious, that's feeling calm?
Where is it that you're not feeling anxious, that's feeling calm?
How is it that you're not feeling anxious, that's feeling calm?
Why is it that you're not feeling anxious, that's feeling calm?
Which part of you is not feeling anxious, that's feeling calm?

Example — all 28 questions, JSON format

$ igor mbl "being stuck" "moving forward" --all --format json

[
  "Who is it that is not being stuck, that's moving forward?",
  "Who else is not being stuck, that's moving forward?",
  "Who knew you were not being stuck, that's moving forward?",
  "Who could imagine not being stuck, that's moving forward?",
  "What is it that's not being stuck, that's moving forward?",
  ...
]

Example — numbered list for use in session notes

$ igor mbl "avoiding conflict" "speaking clearly" --format numbered

1. Who is it that is not avoiding conflict, that's speaking clearly?
2. What is it that's not avoiding conflict, that's speaking clearly?
3. When is it that you're not avoiding conflict, that's speaking clearly?
4. Where is it that you're not avoiding conflict, that's speaking clearly?
5. How is it that you're not avoiding conflict, that's speaking clearly?
6. Why is it that you're not avoiding conflict, that's speaking clearly?
7. Which part of you is not avoiding conflict, that's speaking clearly?

igor kb-info [OPTIONS]

Option	Default	Description
--kb-dir PATH	./kb	Path to the knowledge base directory to inspect.
--verbose	off	List individual files loaded and their sizes, rather than just the summary counts.

Example — standard output

$ igor kb-info

Igor Hypnosis Knowledge Base
=============================
Modules loaded:          22
Techniques indexed:      47
Language patterns:       31
MBL formula templates:   28
Trance themes:           12
KB directory:            /home/user/igor-hypnosis/kb/

All systems ready. Run `igor chat` to start a session.

Example — verbose listing

$ igor kb-info --verbose

Igor Hypnosis Knowledge Base
=============================
Modules loaded: 22
  modules/module_01.json          (4.2 KB)
  modules/module_02.json          (3.8 KB)
  modules/module_03.json          (5.1 KB)
  ... (19 more)

Techniques indexed: 47
  techniques/habs.json            (2.1 KB)
  techniques/mbl_engine.json      (6.3 KB)
  techniques/pcat.json            (4.9 KB)
  ... (44 more)

Language patterns: 31
MBL formula templates: 28
Trance themes: 12

KB directory: /home/user/igor-hypnosis/kb/
All systems ready.

What a broken KB looks like

$ igor kb-info

Igor Hypnosis Knowledge Base
=============================
ERROR: KB directory not found: ./kb
  Expected path: /home/user/igor-hypnosis/kb/

Run `igor kb-info --kb-dir /path/to/kb` to specify a custom location,
or re-download the repository to restore the KB files.

igor sessions list [OPTIONS]

List recent sessions with ID, date, duration, and summary.

Option	Default	Description
--db-path PATH	./.igor/igor.db	Path to the session database.
--client-id ID	all	Filter to sessions tagged with this client ID.
--limit N	10	Number of sessions to show.

$ igor sessions list

ID   Date                Duration   Client      Summary
---  ------------------  ---------  ----------  ---------------------------
12   2025-05-16 21:34    18 min     alice       Procrastination → flow state
11   2025-05-15 19:11    12 min     —           Sanctuary induction (self)
10   2025-05-14 20:05    24 min     alice       Anxiety → calm (MBL + Blitz)
 9   2025-05-12 17:42     9 min     —           MBL practice run
 8   2025-05-10 20:18    31 min     bob         Days of Wonder (full)

igor sessions view --id N [OPTIONS]

Print the full transcript for session N.

Option	Default	Description
--id N	required	Session ID to display (from sessions list).
--db-path PATH	./.igor/igor.db	Database path.
--format FORMAT	plain	plain or json.

igor sessions archive --before DATE [OPTIONS]

Move sessions older than DATE to a compressed archive and remove them from the active database. DATE format: YYYY-MM-DD.

$ igor sessions archive --before 2025-01-01

Archiving 23 sessions before 2025-01-01 ...
Archived to: .igor/archive/sessions-before-2025-01-01.db.gz
Removed from active database.
Active database size: 1.2 MB → 0.3 MB

igor session-state [OPTIONS]

Option	Default	Description
--db-path PATH	./.igor/igor.db	Database path.
--id N	latest active	Session ID to inspect. Defaults to the most recently active session.

$ igor session-state

Session 12 — active
====================
PCAT phase:     ACCESS_RESOURCE
Problem (P):    feeling stuck and unable to start tasks
Resource (R):   feeling focused and in flow
Stage:          2 (DMI/NAS — direct suggestion had no body-check change)
Last technique: Sanctuary induction (complete)
Next suggested: DMI journey from Sanctuary
Turns so far:   14
Elapsed:        11 min