Metadata-Version: 2.4
Name: simulai-cli
Version: 2.1.1
Summary: SimulAI CLI — persistent AI chat in your terminal. SmartRoute across 20+ models, Naira billing, and import your Claude Code / Codex sessions.
Author-email: Simul AI <hello@trysimulai.com>
License: MIT
Project-URL: Homepage, https://trysimulai.com
Project-URL: Documentation, https://docs.trysimulai.com
Project-URL: Repository, https://github.com/Gracemansam/simulai_client
Keywords: ai,llm,cli,nigeria,openai,claude,gemini,claude-code,codex,coding-agent,smartroute
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.24.0

# 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

```bash
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

```bash
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.

```bash
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:

```bash
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:

```bash
simulai chat "explain this error: IntegrityError duplicate key"
```

Attach files:

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

Search the live web:

```bash
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:

```bash
simulai models              # everything
simulai models claude       # filter
```

Pick one for a session:

```bash
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:

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

---

## Coding in your repo

```bash
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:**

```bash
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:

```markdown
# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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 |
| `/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](https://trysimulai.com) · MIT licensed
