Skip to content

getting-started.md

Latest commit

 

History

History
138 lines (105 loc) · 5.39 KB

getting-started.md

File metadata and controls

138 lines (105 loc) · 5.39 KB
Raw

Getting started

This guide takes Chutes Build from installation to a first safe session. The installed binary remains authoritative for version-specific flags:

chutes-build --help

Requirements

The published npm package includes a native executable for Windows, macOS, and Linux and requires Node.js 18 or newer. Building from source requires Rust stable, Git, and the platform C/C++ toolchain used by Rust.

Install

npm install -g chutes-build
chutes-build

For a one-off run:

npx chutes-build

The npm launcher resolves a platform package already installed by npm. It does not fetch an executable from a post-install script.

Authentication

API key

Chutes documents API keys as the fastest way to get started. Create a key at https://chutes.ai/app/settings/api-keys and provide it through one of these paths:

  • run chutes-build login once: it validates the key and saves it for future runs (pipe it via stdin for automation); or
  • press k on the setup screen to enter it when starting without a key (it validates, saves, and resumes); or
  • set CHUTES_API_KEY for the current process (an explicit env key always wins over the saved one).
$env:CHUTES_API_KEY = "your-api-key"
chutes-build

Avoid command-line arguments for secrets because process listings and shell history may expose them. chutes-build logout deletes the saved key.

On Windows, if saving the key fails with permission denied, Controlled folder access is blocking the unsigned binary rather than a missing directory permission: allow chutes-build.exe through it, or use CHUTES_API_KEY (which needs no write). See the README troubleshooting section.

No browser login

There is no account sign-in: no browser or device-code flow, no login screen, no session token. /login and /logout stay unavailable, and login --oauth / login --device-auth are refused. Starting without a key shows a setup screen where you can enter the key inline — never a login option that can only fail.

First session

Run chutes-build from the repository you want the agent to inspect. Chutes Build asks for the applicable folder-trust and tool permissions before performing sensitive operations.

Useful first commands:

Command Purpose
/help Browse commands and shortcuts.
/model Choose Auto or a concrete Chutes model.
/effort Select a supported reasoning mode for the active model.
/usage Inspect this session's token, cost, and inference-speed totals.
/account Inspect the API key's Chutes plan, quotas, usage, and credit.
/docs Open concise guides embedded in the application.
/settings Review interface and runtime preferences.
/rewind or /undo Rewind the current session to a previous turn.
/plan Enter plan mode before implementation.

Auto (Chutes Router) is selected by default when no model preference exists. It sends Chutes' native routing alias default (the pool saved at chutes.ai/app → Model Routing). If that alias cannot resolve, the fallback chain steps down to a live inline pool from the current catalogue (fastest warm model first) so Auto works without a dashboard setup. Pin a concrete catalogue id with /model or CHUTES_BUILD_DEFAULT_MODEL. Use chutes-build models --json when scripts need the resolved catalog.

After each turn, Chutes Build reports the inference speed next to the elapsed time (Worked for 12.4s · 38.2 tok/s); /usage repeats the per-session totals, and chutes-build account (or /account) shows what the API key's plan, quotas, and credit allow.

When revising a proposed plan, type revision notes and press Enter to request changes. An empty Enter does not approve the plan; press a explicitly when the revision prompt is empty and the plan is ready to implement.

Safe operating habits

  • Start in a repository you trust and keep permission prompts enabled.
  • Review commands, destinations, and external network actions before approval.
  • Do not paste secrets into prompts, source files, memory, or committed config.
  • Use --no-memory for a stateless session or when memory text must not be sent to the Chutes-hosted embedding route.
  • Use CHUTES_STRICT_MODEL=1 when an explicit model must never fall back.
  • Treat model output, repository instructions, web content, MCP servers, plugins, and downloaded documents as untrusted input.

Headless use

chutes-build -p "Summarize this repository" --output-format plain
chutes-build -p "Return the package list" --output-format json

Headless-only controls such as --max-turns, --tools, --disallowed-tools, and --json-schema require a headless prompt. See the CLI reference.

Troubleshooting

Problem Check
Command not found Confirm the npm global bin directory is on PATH, or try npx chutes-build.
Empty or stale model list Confirm the credential and network access, then rerun chutes-build models.
Browser unavailable Install Chrome/Edge or set CHUTES_BROWSER_EXECUTABLE.
Video inspection unavailable Install FFmpeg or set CHUTES_FFMPEG_EXECUTABLE, then restart the process.
Terminal preview unavailable Open the typed artifact with its native application; generation output remains on disk.

Configuration paths and every supported public environment variable are in Configuration.