SimulAI CLI

AI in your terminal. Chat that persists across your terminal and the web, an agent that edits code in your repo, and one-command import of your Claude Code or Codex sessions.

Pay in Naira. Switch models mid-conversation. Nothing is locked to one tool.

---

Install

pip install simulai-cli

Requires Python 3.9 or newer.

Windows note: if simulai isn't found after installing, your Python Scripts folder isn't on PATH. Either add it, or run everything as py -m simulai_cli.main <command>.

Log in

simulai login

Your SimulAI account email and password — the same ones you use on the web. Tokens are stored in ~/.simulai/ and refresh automatically, so this is a one-time step per machine.

simulai whoami        # account, balance, current defaults

Upgrading from v1? You must run simulai login once. API keys still work for analyze and scripted use, but conversations, projects, the agent and imports all require a logged-in account.

---

Asking questions

Start an interactive session:

simulai chat

› how do I make a Postgres query with a composite unique constraint?

Follow-up questions just work — keep typing. The session holds the full conversation, so "what about partial indexes?" or "show me that in SQLAlchemy" understands what you were talking about.

Press Ctrl+C or type /exit when done. Nothing is lost — the conversation is saved and appears in the web app at trysimulai.com, where you can pick it up later. Come back to the same folder and simulai chat resumes it.

One-shot, no session:

simulai chat "explain this error: IntegrityError duplicate key"

Attach files:

simulai chat -f app/models.py -f app/schema.sql "why is this insert failing?"

Attach a screenshot straight from your clipboard — no path needed:

simulai chat --paste "what's wrong with this error dialog?"

Search the live web:

simulai chat --web "what changed in Postgres 18?"

---

Choosing a model

By default SmartRoute picks a model per message — cheap ones for simple questions, stronger ones for hard problems. You don't have to think about it.

Browse what's available:

simulai models              # everything
simulai models claude       # filter

Pick one for a session:

simulai chat -m anthropic/claude-sonnet-4-6

Or switch mid-conversation without losing context:

› /model openai/gpt-4o
› /smart              ← hand routing back to SmartRoute

Control effort instead of naming a model:

simulai chat -e fast        # cheapest capable
simulai chat -e max         # one tier up

---

Coding in your repo

cd ~/code/my-project
simulai code "the login endpoint returns 500 when email is missing — fix it"

The agent greps your code, reads the relevant files, and proposes edits. You approve every change as a diff before it touches disk:

╭─────────────── Edit app/api/auth.py ────────────────╮
│ --- a/app/api/auth.py                               │
│ +++ b/app/api/auth.py                               │
│ @@ -42,6 +42,8 @@                                   │
│  def login(body: LoginRequest):                     │
│ +    if not body.email:                             │
│ +        raise HTTPException(422, "email required") │
╰─────────────────────────────────────────────────────╯
Apply? [y/n/a] (y):

y applies it, n declines and tells the agent to try something else, a auto-approves the rest of this run.

After edits it runs your test suite and fixes what it broke.

Useful flags:

simulai code --dry-run "..."       # show what would change, write nothing
simulai code -y "..."              # skip approval prompts
simulai code -m <model> "..."      # pick the model yourself
simulai code --no-verify "..."     # skip the post-edit test run
simulai code -d path/to/sub "..."  # limit it to a subfolder
simulai code -c "..."              # carry facts from earlier runs here
simulai code --save "..."          # keep a record in the web app

Safety: it can't touch files outside the folder you ran it in, destructive shell commands are blocked, every edit is syntax-checked before it's written, and it warns you if your git tree has uncommitted work.

Project instructions

Put a SIMULAI.md at your repo root and every run reads it:

# Conventions
- Python 3.11, snake_case, type hints on public functions
- Tests: pytest -q
- Never edit files under migrations/
- API routes go in app/api/routes/, business logic in app/services/

AGENTS.md and CLAUDE.md work too, so an existing file from another tool is picked up as-is. This is the reliable way to give the agent your conventions — a file you write, review and commit.

Follow-ups while coding

Within a run the agent keeps full context across every step. Between runs it starts fresh, like Claude Code and Codex.

To carry forward what earlier runs did:

simulai code "add an email check to the login endpoint"
simulai code -c "now do the same for the password field"

--continue passes forward the facts — which files changed, which commands ran — not a narrative. It stays on your machine; nothing is uploaded.

Without -c each run is independent, which is usually what you want: an unrelated task doesn't need last week's context, and carrying it costs tokens and can pull the model toward the wrong files.

To keep a record in the web app:

simulai code --save "task"

For anything exploratory, use simulai chat (which does remember conversationally) to work out what you want, then simulai code to do it.

---

Bringing conversations with you

Hit a limit in Claude Code? Bring the session over and keep going on any model:

cd ~/code/my-project
simulai import claude-code

It shows this repo's recent sessions — not a month of every project — and you pick one:

  #  When       Tool         Opening prompt                     Scope
  1  today      claude-code  fix the streaming timeout          exact
  2  2.1d ago   claude-code  add rate limiting to the API       exact

Then simulai chat continues it. The tool noise is stripped on import, so picking up where you left off costs a fraction of the original session.

Other sources:

simulai import codex               # Codex CLI sessions
simulai import scan                # check every supported tool
simulai import file export.json    # a ChatGPT/Claude/Gemini export
simulai import link <share-url>    # a public share link

---

Watching what you spend

Every reply ends with its token count. For the ledger:

simulai wallet       # balance
simulai usage        # what you spent, on what

Inside a chat, /cost shows the balance and this conversation's spend.

Keeping costs down: long conversations re-send their history every turn, so /trim drops older messages from context (they stay saved), and /new starts fresh. For the agent, narrow tasks cost far less than open-ended ones — "fix the null check in wallet.py" beats "review my architecture".

---

Command reference

Command	What it does
simulai login	Log in
simulai chat	Resume this folder's conversation
simulai chat "msg"	One-shot question
simulai code "task"	Agentic coding in this repo
simulai chats	List your conversations
simulai resume	Pick a conversation to continue here
simulai models [filter]	Browse models
simulai projects	List your projects
simulai analyze file.py	Review a single file
simulai analyze file.py --edit	Review and rewrite it in place
simulai import claude-code	Import a Claude Code session
simulai wallet / simulai usage	Balance and spending
simulai config effort max	Change a default
simulai whoami	Account and settings

Inside a chat session

Command	What it does
/model <id>	Switch model (turns SmartRoute off)
/models [filter]	Browse models
/smart	Hand routing back to SmartRoute
/effort fast|balanced|max	Change effort level
/web	Toggle live web search
/mode code|general|marketing|study	Change mode
/project	Attach this chat to a project
/file <path>	Attach a file to your next message
/paste	Attach the image on your clipboard (e.g. a screenshot)
/code	Re-show code blocks from the last reply
/save <file>	Save the last reply
/new [title]	Start a fresh conversation
/trim [n]	Shrink context to the last n messages
/cost · /usage	Spending
/help · /exit	Help, and leave

---

Where things are stored

~/.simulai/config.json    settings and defaults
~/.simulai/auth.json      login tokens
~/.simulai/state.json     which conversation belongs to which folder

Conversations live on your SimulAI account, so they're available on the web and on any machine you log in from.

---

trysimulai.com · MIT licensed