Paradev Project Setup

paradev is an alias for the superset CLI: every superset command here also runs as paradev.

Goal: every new workspace for this repo, a local worktree or a cloud box, comes up ready, with dependencies installed, env present and services reachable, without manual steps.

1. Inspect the repo

Work out what a fresh workspace needs, and ask about anything ambiguous:

• Package manager and install command (lockfiles decide: bun/pnpm/yarn/npm, cargo, uv, ...)
• Env files: .env is usually gitignored, so a new worktree needs it copied from the main checkout or generated from .env.example
• Services (docker-compose, databases), the dev command and its ports
• Monorepo layout (does a step need a cwd?)
• What is already in .superset/: config.toml, or the old config.json, config.local.json and ports.json

2. Write .superset/config.toml

If the repo still has .superset/config.json, convert it. config.json is the old format: Paradev reads config.toml first and ignores config.json when both exist. Tell the user, translate it, and delete config.json and ports.json in the same change.

config.json	config.toml
setup	[setup]
teardown	[archive] (outside cleanup only, see below)
run	[terminals.dev] with default = true
cwd	cwd on each table
.superset/<key>.sh found by name	written out in run
config.local.json with before/after	config.local.toml with full run lists

The format:

[install]                     # cacheable prep, no per-workspace state
run = ["bun install"]

[setup]                       # get this workspace ready
run = ["./.superset/setup.sh"]

[setup.cloud]                 # replaces keys of [setup] in the cloud
run = ["./.superset/setup.cloud.sh"]

[terminals.dev]               # long-running
run = "bun dev"
default = true

[archive]                     # outside cleanup only
run = ["docker compose down"]