Skip to content

Evan1108-Coder/Setupr

BranchesTags

Repository files navigation

Setupr

Intelligent project setup & management CLI. Auto-detects your stack, installs dependencies, configures environments, and keeps projects healthy. Supports 20+ languages with AI-assisted workflows. Features rich TUI with keyboard navigation, real-time status, and smart caching for near-zero AI costs.

Installation

npx setupr

Or install globally:

npm install -g setupr

Quick Start

# Open the project dashboard / home screen
setupr

# Full project setup (scan, plan, install/configure, verify)
setupr setup

# Configure Setupr AI once, globally
setupr auth login

# With minimal prompts (CI-friendly, still stops for blockers/destructive risk)
setupr setup --force

# Plain terminal output (no TUI)
setupr setup --plain

Commands

TUI Commands (Rich Interactive UI)

Command Description
setupr / dashboard Project dashboard with health, git, env, processes, history, and quick commands
setup Full project setup — scan, install runtime, deps, env, verify
status Dashboard/status view with plain, JSON, or TUI output
start Start and track a managed project process
doctor Diagnose environment health (runtimes, deps, ports)
update Check for dependency updates with breaking change warnings
clean Remove artifacts (--deps, --share, --all; positional deps, share, all also work)
auth Manage global Setupr AI provider API keys and models

Non-TUI Commands (Plain Terminal)

Command Description
env [init|check|sync|smart] Manage .env files
ps List Setupr-managed processes
stop [target] Stop one or all managed processes
restart [target] Restart a managed process
info Show project summary
list List available scripts/commands
run <script> Run a project script
switch <version> Switch runtime version
add <package> Smart add dependency
remove <package> Remove dependency
port [number] Check/find/kill port
deps [list|audit|why|licenses] Dependency tree, audit summary, package reasoning, and license checks
config Manage setupr config
help [command] Show global or command-specific help
lock Snapshot environment state
diff Compare current vs locked state
logs [target] Show managed process logs, falling back to package-manager logs
test Detect and run test suite
build Detect and run build command
deploy Run deploy scripts
open [repo|ide] Open in browser/IDE/repo
git Git workflows plus commit-message, PR-description, branch-check, and conflict helper
analyze Deterministic project architecture overview
explain <file> Explain a file from imports, exports, functions, classes, and role signals
refactor <file> Suggest deterministic refactors for a file
todo Scan TODO/FIXME/HACK markers and prioritize them
init Scaffold new projects from stacks or templates
migrate <npm|yarn|pnpm|bun> Migrate package manager metadata and lockfiles
ci <github|gitlab|bitbucket|circleci> Generate CI/CD config
docker <generate|compose|check> Generate Dockerfile/compose files or check Docker readiness
secrets <init|set|get|list|remove|export|import|rotate> Manage encrypted project-local secrets
templates <new|list|save|remove> Create, save, list, or remove templates
workspace <list|run|exec|add|info|check> Operate on monorepo workspaces
health [full|deps|security|outdated|size] Run project health checks
share <export|import|inspect> Export/import shareable setup bundles
notes <add|list|remove|clear> Manage project-local notes in .setupr
history [list] [limit] Show recent project-local Setupr history
context <show|export|import> Export/import notes and history for team handoff
plugin <create|validate|doctor|install|remove|list|info|enable|disable> Manage Setupr plugins and plugin development
lint <run|setup|fix> Run or set up linting
format <run|check|setup> Run or set up formatting
scaffold <type> <name> Generate components, pages, APIs, hooks, models, tests, services, or middleware

Features

Smart Detection

Setupr automatically detects:

  • Languages: TypeScript, JavaScript, Python, Rust, Go, Java, Ruby, PHP, Dart, Elixir, Swift, C#, Kotlin, Scala, and more
  • Frameworks: Next.js, Nuxt, SvelteKit, React, Vue, Angular, Express, Django, Flask, Rails, Spring Boot, and 20+ more
  • Package Managers: npm, yarn, pnpm, bun, pip, poetry, cargo, go, bundler, composer, pub, mix
  • Services: PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ, Elasticsearch, Docker
  • Monorepos: npm workspaces, pnpm workspaces, Turborepo, Lerna, Nx

Detection Priority

  1. .setupr.json config file (explicit, highest priority)
  2. package.json "setupr" field
  3. File-based scanning (lock files, config files)
  4. Content analysis (dependency inspection)
  5. AI fallback (novel situations only)

AI-Powered Intelligence

Setupr uses a 3-tier progressive intelligence system:

  1. Pattern Matching (Level 0) — Free, instant. Handles ~80% of queries
  2. Cached Responses (Level 1) — Free after first hit. Smart deduplication
  3. Live AI (Level 2) — Only for novel situations. Uses compressed DSL for minimal token usage

Supports 7 AI providers (25+ models, plus custom GitHub Models catalog IDs):

Provider Models Env Key
OpenAI gpt-5.4-pro, gpt-5.4-mini, gpt-4o, gpt-4o-mini OPENAI_API_KEY
Anthropic claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5, claude-3.5-sonnet ANTHROPIC_API_KEY
Google gemini-3.1-pro, gemini-3-flash, gemini-2.5-flash-lite GOOGLE_API_KEY
Groq (Llama) llama-4-maverick, llama-4-scout, llama-3.3-70b GROQ_API_KEY
MiniMax minimax-m2.7, minimax-m2.5-lightning MINIMAX_API_KEY
Moonshot (Kimi) kimi-latest, kimi-k2-thinking, kimi-k2-turbo-preview, kimi-k2.5-vision, moonshot-v1-128k MOONSHOT_API_KEY
GitHub Models openai/gpt-4.1, openai/gpt-4.1-mini, openai/gpt-4o, openai/gpt-4o-mini, or any GitHub catalog ID GITHUB_MODELS_API_KEY, GITHUB_TOKEN, or GITHUB_API_KEY

GitHub Models tokens need GitHub Models access; fine-grained PATs or app tokens need models: read.

# Guided setup for provider API keys
setup auth login

# Save one provider API key globally
setup auth set-key github

# View configured providers without printing raw keys
setup auth list

# Test configured providers with tiny requests
setup auth test

# View available models
setup auth models

# Set preferred model
setup auth use openai/gpt-4.1-mini

Setupr stores provider API keys globally in ~/.setupr/secrets.json with file permissions 0600. Raw keys are never printed; setup auth list and setup auth status show only masked keys.

Setupr resolves provider keys in this order:

  1. Shell environment variables, useful for CI or temporary overrides
  2. Global Setupr auth storage from setup auth set-key
  3. Project .env.local / .env for backward compatibility only

The project .env file is for the app being set up, not for Setupr's own API keys. To migrate old project-local provider keys into global auth:

setup auth migrate

When multiple provider keys are present, P_SETUP_AI_MODEL or setup auth use <model> wins. If no model is pinned, Setupr chooses the cheapest configured model from its known local pricing table and shows that choice in the pre-execution warning. GitHub Models catalog/custom pricing is treated as unknown, so GitHub is used automatically only when it is explicitly selected or it is the only configured provider.

Setupr still accepts export KEY=value syntax in project env files for project variables and backward-compatible provider overrides.

Agent-Guided TUI Flow

The setup TUI is an agent workspace, not just a log viewer:

  • Before the dashboard opens, Setupr prints a plain-text warning describing what it may do.
  • Inside the TUI, the main panel shows a time-ordered timeline: system events, AI decisions, user messages, command output, warnings, and confirmations.
  • When the agent needs input, it pauses with an option card above the persistent chat input. You can pick an option, paste KEY=value environment blobs into Other..., or type a plan override such as skip build or prefer pnpm.
  • The AI director can also act on natural language while setup is open: change models, answer the current prompt, fill env values from pasted text, skip or rewrite plan steps, summarize status, and continue with the updated plan.
  • The AI director stays centered on the current setup task, while still allowing brief adjacent questions, clarifications, and steering without being overly strict.
  • For live AI decisions, the director receives a sanitized context packet with project scan data, OS/terminal details, config parameters, current plan, TUI state, notices, dependency/service/port state, terminal diary, and chat history. Secret values are masked before model calls.
  • The same packet includes Setupr's current command capabilities, so the director can recommend or explain git, Docker, CI, workspace, secrets, template, health, plugin, lint, format, and scaffold workflows when they are relevant.
  • User replies appear on the right side of the timeline; AI reasoning and decisions appear inline before execution.
  • --force skips safe prompts and uses defaults where possible, but it does not invent secrets and still stops for serious blockers or destructive choices.

Structured Error Handling

Every command uses the same error format in plain mode and TUI mode:

  • a stable error code such as ENV_TEMPLATE_MISSING, AUTH_STORAGE_INVALID, MISSING_SCRIPT, or AI_PROVIDER_QUOTA_EXHAUSTED
  • a direct explanation of what happened in the current directory/provider/model
  • details that are safe to show, with API keys and tokens masked
  • next steps and recovery options when Setupr can continue

Examples:

  • setup env init stops if .env.example is missing, because Setupr cannot infer required variables. setup env init --force creates an empty .env and explains that no variables were inferred.
  • setup auth list stops on a corrupt ~/.setupr/secrets.json instead of pretending keys are missing, so existing secrets are not accidentally overwritten.
  • command failures are classified as install, build, test, network, permission, timeout, or missing-tool errors when possible.
  • --force skips ordinary prompts, but it does not ignore failed commands, invalid auth storage, missing secrets, or destructive blockers.

Environment Management

# Create .env from .env.example
setup env init

# Overwrite an existing .env from .env.example, or create an empty .env
# when no .env.example exists
setup env init --force

# Check for missing variables
setup env check

# Sync structure with .env.example
setup env sync

# Smart reorganize + auto-fill
setup env smart

Checkpoint & Resume

  • Progress saved to .setupr/checkpoint.json
  • Setup stops on the first failed step and returns a non-zero exit code in plain mode
  • Persists across terminals and reboots
  • Automatically cleaned up on success
  • Resume interrupted setups seamlessly

Project Memory

setup notes add "Use pnpm for installs"
setup notes list
setup history 10
setup context export team-context.json
setup context import team-context.json

Notes are saved in .setupr/notes.json. History uses .setupr/history.jsonl, and context export/import moves a deterministic bundle of notes plus history for team handoff.

Project Dashboard And Processes

setupr
setupr status --json
setupr start
setupr ps
setupr logs
setupr stop
setupr restart dev --watch

setupr with no arguments opens the dashboard, not setup execution. The dashboard summarizes real project signals: scanner results, git state, env status, managed processes, recent history, and available commands. setupr start runs the detected dev, start, serve, develop, or watch script under a Setupr supervisor, writes logs under .setupr/logs/processes, and exposes it through ps, logs, stop, and restart.

Git, Code, And Dependency Intelligence

setupr git commit-message
setupr git pr-description
setupr git branch-check
setupr git conflicts
setupr analyze
setupr explain src/index.ts
setupr refactor src/index.ts
setupr todo
setupr deps audit
setupr deps why react
setupr deps licenses

These commands work offline first. They use deterministic project, file, git, and lockfile signals, then AI-capable flows can layer on --smart where supported.

Plugin Development

setupr plugin create team-tools
cd setupr-plugin-team-tools
npm install
npm run build
setupr plugin validate .
setupr plugin doctor

Plugins are installed into the project-local .setupr/plugins area and registered in global Setupr config. plugin create scaffolds a package with a setupr manifest block and starter entrypoint; plugin validate checks package metadata and entrypoint shape before install/runtime loading.

Flags

Flag Description
--force Skip safe prompts, install what project specifies, and stop only for blockers or destructive choices
--no-tui / --plain Plain terminal output for CI/CD, piping, SSH
--deps With clean, remove dependency/cache artifacts
--share With clean, remove sensitive/local-only files before sharing a project
--all With clean, remove dependencies, build output, caches, and local env files

Configuration

Global config stored at ~/.setupr/config.json:

{
  "ai": { "enabled": true },
  "preferences": {
    "theme": "dark",
    "confirmBeforeInstall": true
  }
}

Provider API keys are stored separately at ~/.setupr/secrets.json and should be managed with setup auth.

Help

setup help
setup help auth
setup auth --help
setup help auth set-key

Global help lists every command. Command help shows subcommands, variations, options, and examples for that command.

Project-level config via .setupr.json:

{
  "language": "TypeScript",
  "framework": "Next.js",
  "runtime": "node",
  "packageManager": "pnpm"
}

TUI Navigation

  • Arrow keys: Move between neighboring panels in the dashboard
  • Tab / Shift+Tab: Move to the next or previous focusable panel
  • Mouse click: Focus a panel in terminals that support SGR mouse events
  • Enter: Confirm / submit focused inputs
  • Esc: Leave or skip the active input when supported
  • q: Quit when focus is not inside an input

The TUI runs in the terminal alternate screen, so exiting returns to the original shell history instead of leaving the dashboard printed in the scrollback. It does not set a background color; Terminal, iTerm2, Ghostty, and other terminal profiles keep control of their own theme/background. Panels are drawn with Unicode box-drawing characters because terminal UIs render in character cells rather than graphical window primitives.

Requirements

  • Node.js >= 18.0.0
  • Terminal with Unicode support (for TUI mode)
  • Recommended for full TUI behavior: alternate screen and SGR mouse support, available in modern Terminal.app, iTerm2, Ghostty, and most current terminal emulators

Release Smoke Testing

Before publishing or after touching scanner, error, auth, env, command execution, or TUI code, run:

npm run smoke:fixtures

This builds the CLI, creates temporary broken/chaotic fixture projects, and checks malformed project files, env failures, corrupt auth storage, missing scripts, failing scripts, no-project setup, monorepo detection, missing logs/locks/remotes, and structured error codes.

The fixture smoke also exercises the expanded command surface through the built CLI, including CI, Docker, secrets, share, workspace, scaffold, and a git shell-injection regression check.

For a best-effort terminal capture smoke on macOS:

npm run smoke:fixtures:tui

That does not replace manual iTerm2/Ghostty visual QA, but it catches obvious TUI launch regressions.

License

MIT

About

AI-powered CLI that sets up any project in seconds. Scans your codebase, installs dependencies, configures environments, and verifies everything works — so you never manually set up a project again. Supports 20+ languages with features rich TUI with keyboard navigation, real-time status, and smart caching for near-zero AI costs.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages