progress.report

A progress tracking platform for developers, agencies, and consultants. Publish project updates and give your clients a live progress page — no logins, no dashboards, no email threads.

You maintain a simple progress.jsonc checklist alongside your code. Run npx progress-report publish whenever something changes. Your client visits a URL and sees exactly where things stand.

How it works

1. You create an account and receive an API key
2. Each client gets a unique 20-character ID and a shareable URL
3. You keep a checklist file (.jsonc) in your project
4. npx progress-report publish pushes the latest state to our API
5. Your client visits view.progress.report/c/{clientId} — always up to date

The viewer applies your custom theme colors and shows your client's branding — phases, tasks, subtasks, completion bars, and any items that need their action.

Quickstart

From zero to a live client progress page in under five minutes.

Step 1 — Create your developer account

Send one request. Your API key is returned immediately and shown only once — save it.

curl -X POST https://progress.report/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'

{
  "accountId": "Kx9mPqR2nYvBt7cWdLa3",
  "email":     "you@yourcompany.com",
  "apiKey":    "pr_live_a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "plan":      "free",
  "note":      "Save your API key — it will not be shown again."
}

Step 2 — Create a client slot

Each of your clients gets their own ID and public URL.

curl -X POST https://progress.report/api/clients \
  -H "Authorization: Bearer pr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp Website Redesign"}'

{
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",
  "name":      "Acme Corp Website Redesign",
  "url":       "https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9"
}

Share that URL with your client right away. It shows a placeholder until you publish.

Step 3 — Set up your project

In your project directory, run the interactive setup wizard:

npx progress-report init

The wizard prompts for your API key, client ID, project name, brand colors, and checklist filename. It creates:

• progress.config.json — your config (contains API key — add to .gitignore)
• progress.jsonc — a starter checklist template

Step 4 — Edit your checklist and publish

Open progress.jsonc and define your phases. Then:

npx progress-report publish

── progress.report ────────────────────────
  Client   : mPqR2nYvBt7cWdLa3Kx9
  Project  : Acme Corp Website Redesign
  Version  : 0.1.0
  Phases   : 3
  Progress : 2/8 done (1 in-progress, 1 need-you, 0 blocked)
  Publishing… ✓

  Live at: https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9
  v0.1.0 · 2026-04-04

Publish again any time something changes. Your client's URL always reflects the latest state.

CLI Guide

The progress-report CLI is the primary way to publish updates. No global install required — use npx.

init

Set up a new project. Run once per project directory.

npx progress-report init

Creates progress.config.json and a starter progress.jsonc template.

publish

Read your checklist and push it to the API.

# Basic publish
npx progress-report publish

# Auto-increment patch version (1.0.0 → 1.0.1)
npx progress-report publish --bump

# Set an explicit version
npx progress-report publish --version 2.0

# Preview payload without making the API call
npx progress-report publish --dry-run

# Use a specific config file (multiple clients per repo)
npx progress-report publish --config ./client-acme/progress.config.json

status

Fetch and display the currently published progress in your terminal.

npx progress-report status

── progress.report · mPqR2nYvBt7cWdLa3Kx9 ────────────────
  Project  : Acme Corp Website Redesign
  Version  : 0.3.0
  Updated  : 2026-04-04
  Progress : 4/9 items done

  ● Discovery  [Complete]
      ●  Requirements workshop
      ●  Content audit
  ◑ Design  [In Progress]
      ●  Wireframes
      ◑  Visual design
      ▲  Client approval
  ○ Development  [Pending]
      ○  Frontend build
      ○  Go live

  View: https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9

progress.config.json

Created by init. Lives in your project root. Add to .gitignore — it contains your API key.

{
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",
  "apiKey":    "pr_live_...",
  "endpoint":  "https://progress.report",
  "checklist": "./progress.jsonc",
  "client": {
    "name":    "Acme Corp Website Redesign",
    "company": "Acme Corp",
    "tagline": "Website Redesign — Build Progress",
    "footer":  "Acme Corp · progress.report"
  },
  "theme": {
    "primary":      "#1D4ED8",
    "primaryLight": "#3B82F6",
    "accent":       "#10B981"
  }
}

Multiple clients in one repo

Keep separate config files per client and use --config:

npx progress-report publish --config ./clients/acme/progress.config.json
npx progress-report publish --config ./clients/bravo/progress.config.json

Checklist Schema

The progress.jsonc file is the only thing you edit regularly. JSONC (JSON with Comments) is fully supported.

{
  // Status values: done | in_progress | you | pending | blocked

  "project":   "Acme Corp Website Redesign",
  "version":   "0.3.0",
  "updatedAt": "2026-04-04",  // auto-stamped on every publish

  "phases": [
    {
      "id":     "1",
      "name":   "Discovery",
      "status": "done",
      "tasks": [
        {
          "id":       "1.1",
          "name":     "Requirements workshop",
          "status":   "done",
          "subtasks": [
            { "id": "1.1.1", "name": "Stakeholder interviews", "status": "done" },
            { "id": "1.1.2", "name": "Technical requirements doc", "status": "done" }
          ]
        }
      ]
    },
    {
      "id":     "2",
      "name":   "Design",
      "status": "in_progress",
      "tasks": [
        { "id": "2.1", "name": "Wireframes",      "status": "done",        "subtasks": [] },
        { "id": "2.2", "name": "Visual design",  "status": "in_progress", "subtasks": [] },
        { "id": "2.3", "name": "Client approval", "status": "you",         "subtasks": [] }
      ]
    }
  ]
}

Status values

you is the most powerful status — it shows the client exactly what they need to do. Items marked you get a prominent orange badge and appear in the action-needed count at the top of the page.

Theming

Set colors in progress.config.json under the theme key. All values are CSS hex colors. The most impactful fields:

Developer Portal

dev.progress.report is your dashboard for managing clients, editing themes, and accessing your API key — no CLI required.

Signing in

Enter your API key (pr_live_...) on the Sign In tab. Your key is stored in localStorage and never sent anywhere except the API.

Dashboard

The dashboard shows all your client projects as tiles. Each tile displays:

• Project name and client ID
• Overall progress percentage
• Color swatches from the active theme
• Direct link to the live viewer page

Color palette editor

Click any tile to open the client detail view. The palette editor lets you set 11 CSS custom properties — primary, accent, background, card, text, and more — with a live mini-preview that updates as you type. Saving applies the theme to the live viewer immediately without republishing your checklist.

Creating an account without the CLI

Use the Create Account tab on the portal sign-in screen. Enter your email and your API key is returned once — copy it immediately.

Build · Tests · Compliance

Publish multiple progression types in a single payload — the viewer shows each as a named tab. Tabs only appear when more than one category exists.

How categories work

The top-level phases array is always the Build tab. Any additional categories are passed in the categories object alongside it. The viewer renders each category as a separate tab with its own progress bar and legend.

Built-in category IDs

Any other id uses the build tab rendering with a capitalized label.

Publish payload with categories

{
  "clientId": "acme-website",
  "phases": [
    // Build tab — same structure as always
    { "id": "1", "name": "Discovery", "status": "done", "tasks": [] }
  ],
  "categories": {
    "tests": {
      "label": "Unit Tests",    // optional — overrides built-in label
      "phases": [
        {
          "id": "AUTH", "name": "Auth Service", "status": "done",
          "tasks": [
            { "id": "AUTH.1", "name": "Token refresh retries on 401", "status": "done" },
            { "id": "AUTH.2", "name": "Expired token rejected",       "status": "blocked" }
          ]
        }
      ]
    },
    "compliance": {
      "phases": [
        {
          "id": "CC6", "name": "Logical Access Controls", "status": "in_progress",
          "tasks": [
            { "id": "CC6.1", "name": "MFA enforced for all users",    "status": "done" },
            { "id": "CC6.7", "name": "Encryption at rest and transit", "status": "pending" }
          ]
        }
      ]
    }
  }
}

Pre-publishing pending items

You don't need tests to run before publishing the test tab. Publish all test cases with "status": "pending" — the viewer displays them as Not Run. This gives clients and stakeholders full visibility into the planned test surface before a single test executes.

When tests run, republish with real statuses (done = pass, blocked = fail). The tab updates live.

API Reference

Base URL: https://progress.report

Authenticated endpoints require one of:

• Authorization: Bearer pr_live_... header
• X-Api-Key: pr_live_... header

Create a developer account. Returns your API key — shown once.

Request body

{ "email": "you@example.com" }

Response 201

{
  "accountId": "Kx9mPqR2nYvBt7cWdLa3",
  "email":     "you@example.com",
  "apiKey":    "pr_live_a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "plan":      "free",
  "note":      "Save your API key — it will not be shown again."
}

Return the authenticated account's details. Useful for verifying an API key.

Response 200

{
  "accountId":    "Kx9mPqR2nYvBt7cWdLa3",
  "email":        "you@example.com",
  "plan":         "free",
  "apiKeyPrefix": "pr_live_a3b4"
}

Create a new client slot. Returns a client ID and the shareable URL.

Request body

{
  "name":     "Acme Corp Website Redesign",  // required
  "customId": "acme-website",               // optional — 4–24 chars [A-Za-z0-9_-]
  "theme": {                                        // optional
    "primary": "#005691",
    "accent":  "#8CC63F"
  }
}

Response 201

{
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",
  "name":      "Acme Corp Website Redesign",
  "url":       "https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9",
  "createdAt": "2026-04-04T00:00:00.000Z"
}

List all clients belonging to your account.

Response 200

{
  "clients": [
    {
      "id":   "mPqR2nYvBt7cWdLa3Kx9",
      "name": "Acme Corp Website Redesign",
      "url":  "https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9"
    }
  ]
}

Update a client's display name and/or theme. Theme changes are applied to the live viewer immediately — no republish required.

Request body

{
  "name":  "Acme Corp Website Redesign v2",  // optional
  "theme": { "primary": "#005691" }              // optional
}

Response 200

{ "ok": true }

Fetch the latest published progress for a client. This is what the viewer page calls.

Response 200

{
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",
  "project":   "Acme Corp Website Redesign",
  "version":   "0.3.0",
  "updatedAt": "2026-04-04",
  "client": {
    "name":    "Acme Corp Website Redesign",
    "company": "Acme Corp",
    "tagline": "Website Redesign — Build Progress",
    "footer":  "Acme Corp · progress.report"
  },
  "theme": { "primary": "#1D4ED8", "accent": "#10B981" },
  "phases": [ /* ... */ ]
}

Response 404

{ "error": "Client not found", "clientId": "..." }

Push a progress update for a client. Overwrites any previous publish for that client ID.

Request body

{
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",           // required
  "project":   "Acme Corp Website Redesign",    // optional
  "version":   "0.3.0",                           // optional
  "updatedAt": "2026-04-04",                      // optional — defaults to today
  "phases": [                                          // Build tab (required unless categories provided)
    {
      "id": "1", "name": "Discovery", "status": "done",
      "tasks": [
        { "id": "1.1", "name": "Requirements", "status": "done", "subtasks": [] }
      ]
    }
  ],
  "categories": {                                      // optional — adds extra tabs to the viewer
    "tests": {
      "label":  "Unit Tests",
      "phases": [ /* same shape as top-level phases */ ]
    },
    "compliance": {
      "phases": [ /* ... */ ]
    }
  },
  "client": { "name": "...", "company": "...", "tagline": "..." },  // optional
  "theme":  { "primary": "#1D4ED8", "accent": "#10B981" }           // optional
}

Response 200

{
  "ok":        true,
  "clientId":  "mPqR2nYvBt7cWdLa3Kx9",
  "version":   "0.3.0",
  "url":       "https://view.progress.report/c/mPqR2nYvBt7cWdLa3Kx9",
  "updatedAt": "2026-04-04"
}

Error responses

All errors return {"error": "description"} with an appropriate HTTP status.

Compliance Progressions

Track certification work — SOC 2, HIPAA, PCI-DSS, ISO 27001, GDPR — the same way you track a build: phases, tasks, and live status for clients and auditors.

Each compliance model below is a pre-built progression template. Every phase maps to a real control family in the framework, and every task maps to a specific requirement. Publish as the Compliance tab alongside your build and unit test tabs.

CLI (planned)

# Initialize a project with a compliance template pre-loaded
npx progress-report init --template soc2
npx progress-report init --template hipaa
npx progress-report init --template pci-dss
npx progress-report init --template iso27001
npx progress-report init --template gdpr

# Stack multiple frameworks
npx progress-report init --template hipaa --template soc2

SOC 2 Type II

Framework: AICPA Trust Services Criteria (TSC)
Template ID: soc2-type2
Who needs it: SaaS companies, cloud services, any org storing or processing customer data. Required by enterprise procurement in most B2B sales cycles.

Key requirements to know

• CC6.1 — MFA on all production system access. No exceptions for admins.
• CC6.7 — Encryption at rest (AES-256) and in transit (TLS 1.2+) is non-negotiable.
• CC7.4 — Tabletop exercise: you must actually run the incident response playbook, not just write it.
• CC8.1 — Code review before every production deploy. PR approval history is the evidence.
• AUDIT.2 — The 12-month window starts here. Don't wait until you're "ready" — start collecting evidence now.

HIPAA

Framework: U.S. Health Insurance Portability and Accountability Act (2026 modernized rules)
Template ID: hipaa-2026
Who needs it: Healthcare SaaS, apps handling PHI or ePHI, business associates of covered entities (hospitals, clinics, insurers). Required before any healthcare client can share patient data with you.

Key requirements to know

• H1.4 — Business Associate Agreement required with every vendor touching PHI — cloud providers, analytics tools, email services.
• H3.4 — AES-256 at rest is now Required, not Addressable under 2026 rules. "We assessed it as unnecessary" is no longer a valid response.
• H3.6 — Audit logs must be immutable and include actor, action, resource, timestamp, and rationale. Append-only storage (e.g. Cloud Logging, Firestore with no delete) satisfies this.
• H4.2 — 24-hour breach notification to the covered entity (hospital/clinic). Automate the alert; don't rely on a human noticing.
• H5.1 — DSAR workflow must be functional before go-live, not a backlog item.

PCI-DSS v4

Framework: Payment Card Industry Data Security Standard v4.0
Template ID: pci-dss-v4
Who needs it: Any service that stores, processes, or transmits cardholder data (CHD). Required by Visa, Mastercard, and all major card brands. Non-compliance results in fines and loss of card processing ability.

Key requirements to know

• PCI2.1 — PANs (card numbers) must be masked everywhere — logs, support tools, admin UIs. Showing more than the last 4 digits is a violation.
• PCI2.4 — You may never store CVV2, PIN, or full magnetic stripe data after authorization, even encrypted.
• PCI4.1 — Shared accounts in the CDE are a direct violation. Every user must have a unique ID with individual accountability.
• PCI5.3 — Daily log review is required. Automate with SIEM alerting; manual review doesn't scale.
• PCI3.4 — Annual external penetration test must be conducted by a qualified internal resource or approved third party.

ISO 27001:2022

Framework: Information Security Management System (ISMS) — ISO/IEC 27001:2022
Template ID: iso27001-2022
Who needs it: Enterprise SaaS targeting international customers, organizations in regulated industries, and any company where prospects request a formal ISMS certificate rather than a self-attestation questionnaire.

Key requirements to know

• ISO2.4 + ISO3.7 — The Statement of Applicability (SoA) is the single most important document for the audit. It lists every Annex A control, whether you've applied it, and why (or why not). Start it early.
• ISO3.1 (A.5.15) — Access control policy must be implemented and reviewed. Having the policy isn't enough — the auditor will check that it's being followed.
• ISO4.2 — You must conduct at least one internal audit before the certification audit. It cannot be done by the same person responsible for the area being audited.
• ISO5.1 — Choose a UKAS-accredited (or equivalent national accreditation body) certification body. Non-accredited certificates are not recognized in most enterprise procurement contexts.
• ISO5.2 — Stage 1 is a documentation review. Have your ISMS policy, risk register, SoA, and internal audit report complete before scheduling it.

GDPR

Framework: EU General Data Protection Regulation (Regulation 2016/679)
Template ID: gdpr
Who needs it: Any service with EU users or that processes EU personal data — regardless of where the company is based. Fines up to €20M or 4% of global annual turnover, whichever is higher.

Key requirements to know

• G1.1 (Art. 30) — The ROPA must list every processing activity: what data, why, who has access, how long it's kept, where it's stored. Controllers with <250 employees may be exempt from some ROPA requirements, but documenting it is best practice regardless.
• G1.3 — Every processing activity needs a documented legal basis. "We thought it was fine" is not a legal basis. Common bases: consent, performance of a contract, legal obligation, legitimate interests (requires balancing test).
• G2.1 — Subject Access Requests must be fulfilled within 30 days. Build the export workflow before you have users, not after you receive your first SAR.
• G3.3 — Cookie consent banners must have no pre-ticked boxes and must make declining as easy as accepting. "Reject all" must be one click.
• G4.2 — Breach notification to the supervisory authority (e.g. ICO in the UK, CNIL in France) within 72 hours of becoming aware. You don't need to know the full scope — report what you know and update later.
• G4.4 — Data leaving the EU to a non-adequate country (e.g. the US) requires a transfer mechanism. Standard Contractual Clauses (SCCs) are the most common; check the EU Commission's adequacy list for your destination country.

Interaction with other frameworks

GDPR overlaps with HIPAA (both cover breach notification and data subject rights), ISO 27001 (both require a DPIA-equivalent for high-risk processing), and PCI-DSS (both require data minimization and documented retention policies). If you're pursuing multiple certifications, map the overlapping controls first — work done for one often satisfies another.

Client IDs

Each client gets a 20-character ID from the base-62 alphabet (A–Z a–z 0–9). Example: Kx9mPqR2nYvBt7cWdLa3

• 119 bits of entropy — guessing is not feasible
• Permanent — the same ID is used for every publish; the URL never changes
• Account-scoped — a client ID belongs to the account that first published to it
• Custom IDs — you can request a readable ID like acme-website when creating a client (4–24 chars, [A-Za-z0-9_-])

Security

API keys

• Format: pr_live_ prefix + 48 hex characters
• Stored as SHA-256 hashes server-side — cannot be recovered, only rotated
• Shown once at account creation — store in a password manager or secrets vault
• Pass via Authorization: Bearer header or X-Api-Key header

What to keep out of version control

Add this to your project's .gitignore:

progress.config.json

Public progress pages

Anyone with a client ID URL can view that progress page. IDs are 20 characters of base-62 — 119 bits of entropy — making enumeration infeasible. Don't include genuinely sensitive details (passwords, internal codenames, PII) in task names.

Data retention

Each publish call fully replaces the previous snapshot for that client ID. No history is stored — the API always serves the most recent publish.