docs: help cmd - pici@07ea8af

Commit `07ea8af`

Eric Bower · 2026-08-12 09:35:28 -0400 EDT

parent a2bd0c4

docs: help cmd

1 files changed, +71, -9

M main.go

+71, -9

......@@ -190,7 +190,57 @@ func newLogger(space string, levelStr string) *slog.Logger {
}

func printMainHelp() {
	fmt.Println(`pici — minimal parallel CI runner & monitor powered by zmx
	fmt.Println(`pici - minimal parallel CI runner & monitor powered by zmx

HOW IT WORKS: pici runs your project's CI pipeline defined in pico.sh:
  1. Syncs workspace to a clean temporary directory (/tmp).
  2. Executes pico.sh inside zmx, running each task in its own isolated PTY.
  3. Bring your own isolation: tasks run on host unless wrapped (e.g. Docker, Podman, Nix).
  4. Tasks execute serially ('zmx run <name> <cmd>') or concurrently in detached mode ('zmx run <name> -d <cmd>').
  5. Concurrent background tasks are joined using 'zmx wait "*"' to block until all complete.
  6. Streams live terminal output & generates HTML reports in /tmp/pici-artifacts/.
  7. Interactive debugging: on failure, attach with 'zmx attach <session>' to inspect logs or rerun commands.
  8. Optionally rsyncs rendered logs & artifacts to a destination when specified.

PROJECT SETUP
  1. Create a pico.sh script in your project root:

       #!/usr/bin/env bash
       set -euo pipefail

       # Read environment metadata (with fallbacks for standalone execution)
       JOB_ID="${PICI_JOB:-local}"
       REPO="${PICI_REPO:-myrepo}"
       BRANCH="${PICI_BRANCH:-main}"
       COMMIT="${PICI_COMMIT:-dev}"
       EVENT="${PICI_EVENT:-local}"
       ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"

       echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"

       # Run serial setup step on host or container
       zmx run setup npm install

       # Run concurrent steps using Docker for environment isolation
       zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
       zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...

       # Wait for all background steps to finish
       zmx wait "*"

  2. Make it executable: chmod +x pico.sh
  3. Run locally:        pici

ENVIRONMENT VARIABLES: pici injects these vars into pico.sh:
    PICI_JOB            Unique job identifier (timestamp or commit SHA)
    PICI_REPO           Repository name (default: directory basename)
    PICI_EVENT          Event type ('local', 'git.push', 'git.tag')
    PICI_BRANCH         Git branch name (auto-detected)
    PICI_COMMIT         Git commit SHA (auto-detected)
    PICI_TAG            Git tag name (set for tag events)
    ZMX_SESSION_PREFIX  Internal session prefix managed by pici

  Pass custom env vars or overrides with -e / -env (e.g. pici -e CGO_ENABLED=0).

LOCAL DEVELOPER USAGE
  pici [destination] [flags]                  Run ./pico.sh locally in /tmp & render HTML logs

......@@ -219,16 +269,28 @@ func printMissingPicoHelp(cwd string) {

To run local CI tasks, create a pico.sh script in your project root:

  #!/usr/bin/env bash
  set -euo pipefail
	#!/usr/bin/env bash
	set -euo pipefail

  # Run parallel steps using zmx
  zmx run lint -d <your lint command>
  zmx run test -d <your test command>
	# Read environment metadata (with fallbacks for standalone execution)
	JOB_ID="${PICI_JOB:-local}"
	REPO="${PICI_REPO:-myrepo}"
	BRANCH="${PICI_BRANCH:-main}"
	COMMIT="${PICI_COMMIT:-dev}"
	EVENT="${PICI_EVENT:-local}"
	ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"

  # Wait for all steps to finish
  zmx wait "*"
  printf "\x1b[32msuccess!\x1b[0m\n"
	echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"

	# Run serial setup step on host or container
	zmx run setup npm install

	# Run concurrent steps using Docker for environment isolation
	zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
	zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...

	# Wait for all background steps to finish
	zmx wait "*"

For full command documentation and daemon options, run:
  pici help

...	...		@@ -190,7 +190,57 @@ func newLogger(space string, levelStr string) *slog.Logger {
190	190		}
191	191
192	192		func printMainHelp() {
193		-	fmt.Println(`pici — minimal parallel CI runner & monitor powered by zmx
	193	+	fmt.Println(`pici - minimal parallel CI runner & monitor powered by zmx
	194	+
	195	+	HOW IT WORKS: pici runs your project's CI pipeline defined in pico.sh:
	196	+	1. Syncs workspace to a clean temporary directory (/tmp).
	197	+	2. Executes pico.sh inside zmx, running each task in its own isolated PTY.
	198	+	3. Bring your own isolation: tasks run on host unless wrapped (e.g. Docker, Podman, Nix).
	199	+	4. Tasks execute serially ('zmx run <name> <cmd>') or concurrently in detached mode ('zmx run <name> -d <cmd>').
	200	+	5. Concurrent background tasks are joined using 'zmx wait "*"' to block until all complete.
	201	+	6. Streams live terminal output & generates HTML reports in /tmp/pici-artifacts/.
	202	+	7. Interactive debugging: on failure, attach with 'zmx attach <session>' to inspect logs or rerun commands.
	203	+	8. Optionally rsyncs rendered logs & artifacts to a destination when specified.
	204	+
	205	+	PROJECT SETUP
	206	+	1. Create a pico.sh script in your project root:
	207	+
	208	+	#!/usr/bin/env bash
	209	+	set -euo pipefail
	210	+
	211	+	# Read environment metadata (with fallbacks for standalone execution)
	212	+	JOB_ID="${PICI_JOB:-local}"
	213	+	REPO="${PICI_REPO:-myrepo}"
	214	+	BRANCH="${PICI_BRANCH:-main}"
	215	+	COMMIT="${PICI_COMMIT:-dev}"
	216	+	EVENT="${PICI_EVENT:-local}"
	217	+	ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"
	218	+
	219	+	echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"
	220	+
	221	+	# Run serial setup step on host or container
	222	+	zmx run setup npm install
	223	+
	224	+	# Run concurrent steps using Docker for environment isolation
	225	+	zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
	226	+	zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...
	227	+
	228	+	# Wait for all background steps to finish
	229	+	zmx wait "*"
	230	+
	231	+	2. Make it executable: chmod +x pico.sh
	232	+	3. Run locally: pici
	233	+
	234	+	ENVIRONMENT VARIABLES: pici injects these vars into pico.sh:
	235	+	PICI_JOB Unique job identifier (timestamp or commit SHA)
	236	+	PICI_REPO Repository name (default: directory basename)
	237	+	PICI_EVENT Event type ('local', 'git.push', 'git.tag')
	238	+	PICI_BRANCH Git branch name (auto-detected)
	239	+	PICI_COMMIT Git commit SHA (auto-detected)
	240	+	PICI_TAG Git tag name (set for tag events)
	241	+	ZMX_SESSION_PREFIX Internal session prefix managed by pici
	242	+
	243	+	Pass custom env vars or overrides with -e / -env (e.g. pici -e CGO_ENABLED=0).
194	244
195	245		LOCAL DEVELOPER USAGE
196	246		pici [destination] [flags] Run ./pico.sh locally in /tmp & render HTML logs

...	...		@@ -219,16 +269,28 @@ func printMissingPicoHelp(cwd string) {
219	269
220	270		To run local CI tasks, create a pico.sh script in your project root:
221	271
222		-	#!/usr/bin/env bash
223		-	set -euo pipefail
	272	+	#!/usr/bin/env bash
	273	+	set -euo pipefail
224	274
225		-	# Run parallel steps using zmx
226		-	zmx run lint -d <your lint command>
227		-	zmx run test -d <your test command>
	275	+	# Read environment metadata (with fallbacks for standalone execution)
	276	+	JOB_ID="${PICI_JOB:-local}"
	277	+	REPO="${PICI_REPO:-myrepo}"
	278	+	BRANCH="${PICI_BRANCH:-main}"
	279	+	COMMIT="${PICI_COMMIT:-dev}"
	280	+	EVENT="${PICI_EVENT:-local}"
	281	+	ZMX_SESSION_PREFIX="${ZMX_SESSION_PREFIX:-local.}"
228	282
229		-	# Wait for all steps to finish
230		-	zmx wait "*"
231		-	printf "\x1b[32msuccess!\x1b[0m\n"
	283	+	echo "Running CI for $REPO ($BRANCH@$COMMIT, job: $JOB_ID, event: $EVENT)"
	284	+
	285	+	# Run serial setup step on host or container
	286	+	zmx run setup npm install
	287	+
	288	+	# Run concurrent steps using Docker for environment isolation
	289	+	zmx run lint -d docker run --rm -v "$(pwd):/app" -w /app golangci/golangci-lint golangci-lint run
	290	+	zmx run test -d docker run --rm -v "$(pwd):/app" -w /app golang:1.26 go test ./...
	291	+
	292	+	# Wait for all background steps to finish
	293	+	zmx wait "*"
232	294
233	295		For full command documentation and daemon options, run:
234	296		pici help

Commit 07ea8af

Commit `07ea8af`