Menu
简体中文
On this page

Quickstart

Docs home · 简体中文

This guide uses the recommended npm alpha path to get you into a useful Sigil session in a real repository. For every other install channel and all update or uninstall instructions, use Installation.

Before You Begin

You need:

For the smoothest first run, start in a repository where you can inspect git diff before and after the session.

1. Install Sigil

Install the current alpha from the scoped npm package:

npm install -g @sigil-ai/sigil@alpha

Homebrew, Cargo, source builds, release archives, updates, and uninstall commands are documented only in Installation, so those instructions stay current in one place.

Confirm the binary is on PATH:

sigil --version

If your shell cannot find sigil, check the installer output and confirm its binary directory is on PATH.

2. Start In The Workspace You Want To Edit

Open the project you want Sigil to operate on:

cd /path/to/workspace
sigil

Sigil treats this launch directory as the active workspace when the config uses workspace.root = ".", which is the normal Quick Setup result.

3. Complete Quick Setup

If no usable config exists, Sigil opens Quick Setup. Confirm:

  1. Workspace: the repository or directory you want Sigil to inspect and modify.
  2. Provider/model: the backend model Sigil should use.
  3. Authentication: the API key or equivalent credential.

For temporary local use, choose the provider first, then export the provider-specific variable listed in the authentication map before launching sigil. Each provider page includes its exact shell command; Sigil does not use one provider-neutral API key variable.

If you save an API key through Quick Setup or /config, it is written as plaintext to the local config file. Do not commit a real sigil.toml.

4. Run The First Checks

Inside the TUI, run:

/doctor

This reports config loading, workspace, sessions, provider/auth, MCP, code intelligence, and terminal compatibility.

Then ask a read-only repository question:

Explain this repository structure. Point out the important directories, test locations, configuration files, and user documentation.

Read-only file and search tools usually run without approval. This is a good first test because it lets you watch how Sigil reads context before making changes.

5. Try A Small Safe Task

Use a narrow, reviewable prompt:

Review the README and docs index for unclear user-facing wording. Suggest improvements first; do not edit files yet.

Then ask for a small edit:

Apply only the README wording changes you just proposed.

When Sigil requests a file-changing tool, review:

After approval, inspect your repository normally:

git diff

6. Use Planning For Larger Work

For work that needs multiple steps, start directly with:

/task improve installation docs for macOS, Linux, and Windows users

Sigil writes a durable task plan. You can guide or correct the next step in the composer. To continue without extra guidance:

/task continue

For a larger edit where you want a read-only planning pass first, run /plan <prompt> and accept the plan-ready card only when you want Sigil to create and run the durable task. Planned task state is stored in append-only control records and is restored when you reopen the session.

7. End A Session Cleanly

Before committing work produced with Sigil:

git diff
sigil doctor

Run project-specific tests or formatters as appropriate. Sigil can run commands when allowed, but you should still review the final diff and test output.

Next