# CLI reference

> Every guijam command and option. init, doctor, provider list and provider use, plus their flags, exit codes and the checks doctor runs.

Run these in your app's folder with `npx`, or with your package manager's runner.

```txt
Usage: guijam <command> [options]
```

## Commands

| Command                                         | What it does                                                                                                                                                                        |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx guijam init`                               | Sets up GUIJam: adds the package, wires your framework's config, and picks your AI tool and logs it in. Safe to run again.                                                          |
| `npx guijam doctor`                             | Checks Node, your framework, the config wiring, the `gjd` daemon and your AI tool's login.                                                                                          |
| `npx guijam doctor --probe`                     | Also sends one short test request to your AI tool. Spends a few tokens.                                                                                                             |
| `npx guijam provider list`                      | Lists the AI coding CLIs GUIJam can drive, and whether each is installed and logged in.                                                                                             |
| `npx guijam provider use <id>`                  | Switches the AI tool: `claude-code`, `codex`, `opencode`, `qwen-code` or `gemini-cli`.                                                                                              |
| `npx guijam provider use <id> --model <model>`  | Also picks the model, such as `deepseek/deepseek-chat` with OpenCode.                                                                                                               |
| `npx guijam provider use <id> --effort <level>` | Sets the effort for every request: `low`, `medium` or `high`. Claude Code and Codex use it. See [Choose an effort](https://guijam.francistinao.com/docs/ai-tools#choose-an-effort). |
| `npx guijam --help`                             | Shows every command and option.                                                                                                                                                     |
| `npx guijam --version`                          | Shows the installed version.                                                                                                                                                        |

Running `guijam` with no command shows the banner and the help. An unknown command prints `Unknown command "<name>".` with the help, and exits with code 1.

## Options

| Option            | What it does                                                                        |
| ----------------- | ----------------------------------------------------------------------------------- |
| `-y`, `--yes`     | Uses the defaults instead of asking                                                 |
| `--provider <id>` | The AI tool to use: `claude-code`, `codex`, `opencode`, `qwen-code` or `gemini-cli` |
| `--model <id>`    | The model to use with it, such as `deepseek/deepseek-chat`                          |
| `--skip-install`  | Doesn't add `guijam` to `package.json`                                              |
| `--cwd <dir>`     | Runs in another folder                                                              |
| `--probe`         | Sends one short test request to your AI tool                                        |
| `-h`, `--help`    | Shows the help                                                                      |
| `-v`, `--version` | Shows the version                                                                   |

`--yes`, `--provider`, `--model`, `--skip-install` and `--cwd` apply to `init`. `--probe` applies to `doctor`. The `provider` commands work on your user-wide settings, so `--cwd` doesn't apply to them.

## init

```bash
npx guijam@latest init
```

In order, `init`:

1. Detects your project: package manager, framework, UI library and styling.
2. Adds `guijam` as a dev dependency with your package manager, unless `--skip-install` is set or it's already there.
3. Wires your framework's config. If the config can't be edited safely, it prints the lines to add.
4. Lists the AI coding CLIs on your machine and saves the one you pick. With OpenCode, it also lists the models, leaving out OpenCode's own free models, which don't answer GUIJam.
5. Offers to install your AI tool or run its login, when needed.
6. For OpenCode, Qwen Code and Gemini CLI, offers to send one short test request, which spends a few tokens. A passing request counts as logged in.
7. Adds `.guijam/` to `.gitignore`.
8. Prints your next steps.

`init` asks questions only in an interactive terminal. With `--yes`, or when it isn't interactive, it picks your active AI tool, else the first one that is logged in, else the first one installed. It doesn't install or log in to anything then; it tells you what's left to do.

| Exit code | Meaning                                                             |
| --------- | ------------------------------------------------------------------- |
| `0`       | Setup finished. Steps it couldn't finish are flagged in the output. |
| `1`       | Setup failed, such as no `package.json` in the folder.              |
| `130`     | You cancelled.                                                      |

## doctor

```bash
npx guijam doctor
```

`doctor` runs these checks, in order:

1. Node is `^20.19.0` or `>=22.12.0`.
2. Your framework is supported.
3. In Next.js, the version is 16.3 or newer.
4. Vite is version 6, 7 or 8. Other versions are a warning, not a failure.
5. `guijam` is in your `package.json`.
6. Your framework's config loads GUIJam.
7. `vite-plugin-pwa` with its dev service worker on is a warning, because it can serve a cached page without the toolbar.
8. A `gjd` binary exists for your platform, and runs.
9. Your AI tool, the active one or else the first one logged in, is installed and logged in.
10. With `--probe`, that tool answers one short test request. Doctor prints how long it took, such as "OpenCode answered in 6.3 s to a test request", or the tool's reason for failing.

```bash
npx guijam doctor --probe
```

`--probe` makes a real request, so it spends a few tokens from your plan or your API credits.

It ends with "Everything looks good." or the number of problems found, and exits with code 1 when anything failed. See [Troubleshooting](https://guijam.francistinao.com/docs/troubleshooting) for each message.

## provider

```bash
npx guijam provider list
npx guijam provider use opencode --model deepseek/deepseek-chat
```

`provider use` saves your choice in your user's [config.toml](https://guijam.francistinao.com/docs/reference/configuration#configtoml), keeping anything else in that file. It applies to every project, on your next request. `npx guijam provider` on its own runs `provider list`.

### Advanced provider commands

These aren't in `--help`, but work the same way:

| Command                                  | What it does                                                                                                                                                                                                                           |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx guijam provider models <id>`        | Lists the models a tool can run. Only OpenCode lists models. Add `--json` for JSON output.                                                                                                                                             |
| `npx guijam provider test <id> --runs 5` | Runs a real request through the tool and reports timings. `--runs` defaults to 1. `--model` picks the model, else it uses your saved model, else the tool's fast model. `--effort` picks the effort, else your saved effort, else low. |

> **provider test spends tokens**
>
> `provider test` makes real requests with your AI tool, so it uses your plan or your API credits.
