CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PCLI is a Go CLI tool for interacting with the Planka (v2.0) project management API. It uses the Cobra framework with minimal dependencies (only Cobra + standard library).

Build & Test Commands

go build -o pcli .                # Build for development
./build.sh                        # Multi-platform release build (linux/darwin/windows)
./test.sh                         # Integration tests (requires live Planka instance)

Integration tests require PLANKA_URL and PLANKA_API_KEY environment variables pointing to a running Planka instance.

There is no unit test suite or linter configured — tests are shell-based integration tests in test.sh.

Architecture

Entry point: main.go → cmd.Execute()

Package layout:

cmd/ — Cobra command definitions, one file per resource (project.go, board.go, card.go, etc.)
client/ — HTTP API client, one file per resource matching cmd/ structure
model/types.go — All domain types (Project, Board, Card, List, Label, Task, Comment, etc.)
output/output.go — Dual-format output: JSON envelope ({data, error}) or human-readable table via tabwriter
logging/logging.go — slog-based structured JSON logging to stderr

Command hierarchy: pcli <resource> <action> (e.g., pcli card create --list <id> --name "task")

Key patterns:

Global flags (--format, --url, --api-key, --log-level) set in cmd/root.go PersistentPreRunE, which validates config and initializes the API client
Client methods follow List*/Get*/Create*/Update*/Delete* naming
API responses use typed structs with included relationships (e.g., board responses include lists and cards)
friendlyAPIError() in cmd/errors.go translates HTTP status codes to contextual messages
DoWithFallback in client supports trying alternate API endpoint patterns
Output uses reflection-based table rendering per type

Configuration: Environment variables PLANKA_URL and PLANKA_API_KEY, overridable via CLI flags.

Adding a New Resource

Define model structs in model/types.go
Add client methods in client/<resource>.go
Add command definitions in cmd/<resource>.go with subcommands (list, get, create, update, delete)
Wire the parent command into root.go init()

Planka Sync

IMPORTANT After completing any opsx workflow (/opsx:new, /opsx:ff, /opsx:continue, /opsx:apply, /opsx:verify, /opsx:archive, /opsx:bulk-archive), automatically reconcile Planka board state by running the sync script:

PROJECT_NAME=$(yq -r '.planka.project' project.yaml)
BOARD_NAME=$(yq -r '.planka.board' project.yaml)
kanban-project-sync --project "$PROJECT_NAME" --board "$BOARD_NAME" --background

The script handles concurrency (flock-based locking with coalescing pending queue). If the script is not on PATH or fails, log a brief warning and continue. Never block or retry — Planka sync is best-effort.

3.0 KiB Raw Permalink Blame History