---
title: Quickstart
path: quickstart
status: published
---

# QUICKSTART

Zero-to-first-prompt in about five minutes. Assumes a **ScaiGrid**
endpoint and either a **ScaiKey** account or a ScaiGrid `sgk_live_...`
**API key**.

## 1. Install

Pick one. Both end up with a `scaiflux` command on your `$PATH`.

### Option A — standalone binary (no Python needed)

The simplest option for end users. One file, no dependencies.

```bash
# Replace VERSION with the release you want.
VERSION=0.1.0
BASE=https://downloads.scailabs.ai/dist/scaiflux
NAME=scaiflux-${VERSION}-linux-x86_64

curl -fLO "$BASE/$NAME.gz" \
  && curl -fLO "$BASE/$NAME.gz.sha256" \
  && sha256sum -c "$NAME.gz.sha256" \
  && gunzip "$NAME.gz" \
  && chmod +x "$NAME" \
  && mkdir -p ~/.local/bin \
  && mv "$NAME" ~/.local/bin/scaiflux
```

Make sure `~/.local/bin` is on `$PATH` (most shells already do this;
if not, add `export PATH="$HOME/.local/bin:$PATH"` to your rc file).
Linux x86_64 only at v0.1.0 — see [Install](./install) for full
details and troubleshooting.

### Option B — Python install (devs / contributors)

Use this if you want to hack on ScaiFlux itself, or if you need the
MCP client or plugin entry-point discovery (neither is in the binary).

```bash
git clone <this repo>           # adjust to your remote
cd scaiflux
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"     # dev extras + MCP client support
```

Or via `pipx` for the wheel without cloning:

```bash
pipx install scaiflux
```

## 2. Setup

Recommended — run the wizard:

```bash
scaiflux setup
```

Three prompts: pick an endpoint (defaults to ScaiLabs ScaiGrid at
`https://scaigrid.scailabs.ai`), paste a ScaiGrid API key
(`sgk_live_...`), pick a default model from the discovered catalog,
and optionally scaffold `.scaiflux.json` + `SCAIFLUX.md` in the
current directory. The session is cached in
`~/.scaiflux/credentials.json` (mode 0600). `scaiflux logout` wipes
it.

Already have an OAuth-capable ScaiKey account and prefer the browser
flow? Skip the wizard and run `scaiflux login` directly:

```bash
export SCAIGRID_BASE_URL="https://scaigrid.example.com"
export SCAIKEY_BASE_URL="https://scaikey.example.com"
export SCAIKEY_TENANT="your-tenant-slug"
export SCAIKEY_CLIENT_ID="scaiflux-cli"     # pre-registered public client
scaiflux login
```

Or fully headless with an API key (no wizard prompts):

```bash
scaiflux login --scaigrid-url https://scaigrid.scailabs.ai \
               --api-key sgk_live_xxxxxxxx \
               --default-model scailabs/poolnoodle-omni
```

## 3. Verify

```bash
scaiflux doctor
```

Expect a report along these lines:

```text
ScaiFlux doctor — 12/13 checks passed
  ✓ python_version: 3.13.5
  ✓ scaiflux_version: 0.1.0
  ✓ platform: Linux-6.12-x86_64
  ✓ inference_credentials: base_url=https://scaigrid.example.com/oai/v1
  ✓ scaikey_session: stored at /home/you/.scaiflux/credentials.json
  ✓ bash_available: bash is on PATH
  ✓ workspace_writable: /home/you/projects/scaiflux
  · config_loaded: no config files
  ✓ git_available: git on PATH (for /diff, /commit, /release-notes)
  ✓ gh_available: gh on PATH (for /pr, /issue)
  ✓ sandbox_available: unshare, firejail
  ✓ terminal: tty=True term=xterm-256color
  ✓ mcp_servers: (none configured)
  ✓ plugins: (none discovered)
```

Counts vary by host — `git_available` and `sandbox_available` flip to
warnings if the binary isn't installed. `mcp_servers` and `plugins`
report the configured surface; both are empty until you add servers /
plugins.

## 4. First prompt

```bash
scaiflux prompt "what's 2 + 2?"
```

You'll see the response stream to stdout.

## 5. Scaffold a workspace

```bash
cd ~/projects/experiment     # or any directory
scaiflux init
```

Creates:

- `.scaiflux.json` — starter config (`model`, `permissions.mode`, `hooks`).
- `SCAIFLUX.md` — project memory file, loaded into every system prompt.
- `.gitignore` — appends `.scaiflux/sessions/` and
  `.scaiflux/settings.local.json`.

Open `.scaiflux.json` to see the defaults; open `SCAIFLUX.md` to write
project-specific guidance for the assistant.

## 6. First tool invocation

Default permission mode from `scaiflux init` is `workspace-write`. Try:

```bash
scaiflux prompt "create hello.txt with the text 'hi from scaiflux'"
cat hello.txt
```

The assistant invokes `write_file` inline; you'll see a tool_use block
roundtrip, then the synthesis.

## 7. REPL

```bash
scaiflux repl
```

Inside:

```text
scaiflux> /help             # list all slash commands
scaiflux> /files **/*.py    # glob from the slash command surface
scaiflux> /cost             # cumulative tokens + estimated $ for the session
scaiflux> count the lines in README.md
scaiflux> /exit
```

Tab completion covers slash commands, the models discovered at login,
permission modes, and recent session IDs.

## 8. Permission modes

Lock the assistant down:

```bash
scaiflux prompt --permission-mode read-only "delete hello.txt"
# → the write_file attempt returns an is_error result
```

Interactive approval per call:

```bash
scaiflux prompt --permission-mode prompt "run 'ls'"
# → prompt on stderr: Approve tool call 'bash'? [y/N]:
```

Unattended danger mode (skips all prompts):

```bash
scaiflux prompt --dangerously-skip-permissions "..."
```

## 9. JSON output

For scripts / pipelines:

```bash
scaiflux prompt --output-format json "summarize README.md" | jq .message
```

The JSON envelope includes `message`, `model`, `iterations`,
`stop_reason`, `tool_uses`, `tool_results`, `usage`, `estimated_cost`,
and `auto_compaction` (non-null when the token window filled).

## 10. Resume / replay / fork a session

Every run persists to `.scaiflux/sessions/<id>.jsonl`. Resume the most
recent:

```bash
scaiflux prompt --resume latest "continue where we left off"
```

Or by id: `--resume session_1745...`.

Inspect or branch a stored session without resuming it:

```bash
scaiflux session list
scaiflux session replay <id|latest>            # print the transcript
scaiflux session fork <id|latest> --at 3       # branch a new session at turn 3
```

Inside the REPL, the same actions live under `/session
{list,resolve,replay,fork}`.

## 10b. Edit project memory

```bash
scaiflux repl
scaiflux> /memory               # list memory files loaded into the prompt
scaiflux> /memory edit          # opens SCAIFLUX.md in $EDITOR
scaiflux> /memory edit SCAIFLUX.local.md
```

Three memory files are recognized: `SCAIFLUX.md`, `SCAIFLUX.local.md`,
`.scaiflux/instructions.md`. They're loaded into the system prompt in
that order on every turn.

## 10c. Workflow `run` mode

Each workflow that has a clear action accepts a `run` argument that
executes the generated artifact (opt-in, never automatic):

```text
scaiflux> /commit                   # render a conventional commit message
scaiflux> /commit run               # also pipe it into `git commit -F -`
scaiflux> /pr                       # render a PR title + body
scaiflux> /pr run                   # also call `gh pr create`
scaiflux> /issue run fix the readme # call `gh issue create` with this subject
```

Without `run`, the workflows are read-only.

## 11. Add a plugin (optional)

Plugins are directories with a `plugin.json` manifest. Minimal example:

```bash
mkdir -p external-plugins/hello/tools
cat > external-plugins/hello/plugin.json <<'JSON'
{
  "name": "hello",
  "version": "1.0.0",
  "tools": [
    {
      "name": "hello_echo",
      "description": "Echo JSON input verbatim",
      "inputSchema": {"type": "object"},
      "command": "./tools/echo.sh",
      "requiredPermission": "read-only"
    }
  ]
}
JSON

cat > external-plugins/hello/tools/echo.sh <<'SH'
#!/usr/bin/env bash
cat
SH
chmod +x external-plugins/hello/tools/echo.sh
```

Register it in `.scaiflux.json`:

```jsonc
{
  "plugins": {"externalDirectories": ["./external-plugins"]},
  "enabledPlugins": {"hello@external": true}
}
```

Verify:

```bash
scaiflux plugin list
# → hello@external  v1.0.0  (external, enabled, tools=1)  — .../external-plugins/hello
```

The `hello_echo` tool is now in the registry and the model can invoke
it like any built-in tool.

## 12. Configure an MCP server (optional)

If you installed with `[mcp]`, add a server to `.scaiflux.json`:

```jsonc
{
  "mcp": {
    "servers": {
      "search": {"command": "uvx", "args": ["mcp-search"]}
    }
  }
}
```

Verify startup:

```bash
scaiflux mcp status
# → search  [connected]  tools=3
```

Its tools appear as `search__<tool>` in the registry.

## Where to go next

- `USAGE.md` — full subcommand + flag table + slash command inventory.
- `PARITY.md` — parity harness overview; run `pytest tests/parity -q`.
- `CLAUDE.md` — architecture map for contributors.
- `ROADMAP.md` — post-v0.1.0 backlog.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `No inference credentials found` | Run `scaiflux login`, or set `SCAIGRID_API_KEY` + `SCAIGRID_BASE_URL`. |
| `Stored ScaiKey token is expired` | `scaiflux login --refresh` (or `scaiflux login` for a full re-auth). |
| `No model configured` | Pass `--model <slug>`, set `model` in `.scaiflux.json`, or re-run `scaiflux login` and pick a default. |
| Tool blocked unexpectedly | `scaiflux status` — check active permission mode. Raise with `--permission-mode workspace-write`. |
| MCP server not listed | `pip install -e ".[mcp]"` then `scaiflux mcp status` to see the failure reason. |
| Prompt hangs on an interactive approval | You passed `--permission-mode prompt`. Type `y<Enter>` / `n<Enter>` on stdin. |
| `auto_compaction` never fires | Lower the threshold: `export SCAIFLUX_AUTO_COMPACT_INPUT_TOKENS=5000`. |