picassodocs
docs/quickstart.md

Quickstart

Install Picasso, add a model, and take one interactive turn in a couple of minutes. Picasso comes two ways that share the same settings, threads, themes and memory: Picasso for Mac and the CLI/TUI (picasso).

Prerequisites

Install

Picasso for Mac

Download the signed, notarized DMG from https://picassohq.com/download and drag Picasso to Applications. The app updates itself in the background, and the first launch offers a short tour (Help › Take the tour brings it back).

CLI and TUI

npm install -g @picassohq/cli

The CLI package is @picassohq/cli; it installs the picasso command and its pinned engine.

Or ask your agent to check a release and install it for you: picasso about --install-prompt cli (or mac) prints a prompt that verifies the release first. The same prompts are in 14-distribution.md.

From a checkout of this repo:

pnpm install
pnpm build
pnpm picasso

Add a model

picasso provider list                             # every route and whether its key resolves
picasso provider set deepseek-official --key-stdin  # paste the key; or: picasso provider set <route> <key>
picasso provider use deepseek-official
picasso provider check deepseek-official           # each model's window, output limit and levels

picasso models lists every model you can use with its context window, output limit and reasoning levels, and picasso models connections sets the order Picasso falls back through when a provider runs out of quota or fails. A custom OpenAI- or Anthropic-compatible endpoint is picasso provider add.

In the Mac app, open Settings › Providers and pick a provider: Picasso opens that provider's API-key page in your browser, and you paste the key back.

First interactive turn

picasso

Picasso opens on the start page: "What should we build in ‹project›?", your recent threads and an activity heatmap. Type:

tell me what changed in the auth module since main

You should see:

While the turn runs, Enter queues a follow-up; ctrl+enter (or alt+enter) steers it into the running turn; Enter in an empty composer sends the queued message now; ctrl+q interrupts. /tour walks through these keys.

Useful first commands

picasso --help
picasso doctor                 # terminal, engine, model and MCP checks
picasso models
picasso memory list
picasso import --dry-run       # bring in past Claude Code, Codex or OpenCode sessions
picasso goal templates
picasso about --footprint      # what Picasso puts on this computer
picasso update                 # check for a newer Picasso

Inside the TUI:

/help
/model
/usage
/memory
/theme
/tour

Staying current

picasso update checks for a newer Picasso and runs one engine check now; picasso update --install installs a newer npm release. The engine also updates itself in the background: Picasso checks every few hours while idle, verifies a new engine before using it, switches at the next start and rolls back if it fails. Picasso for Mac keeps its bundled engine and installs app updates silently.

Troubleshooting

``bash PICASSO_REDUCED_MOTION=1 picasso ``