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/{developer}/{project}/{view} — 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.

Built for teams that ship

Client communication is broken. Status emails go unanswered. Slack threads lose context. Spreadsheets go stale. progress.report replaces all of it with a single live URL your client can bookmark.

How it compares

Who uses progress.report

Any team that builds software for clients — or that needs to show progress to stakeholders — can use progress.report out of the box.

Integrations & Ecosystem Vision

progress.report is not a compliance tool. It is not a test runner. It is not a CI platform. It is the unified progress layer — the glass panel that reads from the best specialized tools in each domain and surfaces the combined output as a single live page for clients, stakeholders, and auditors.

What works today

You don't need to wait for native integrations. Every tool above produces structured output — JSON, XML, or text — that you can map to a progress.report payload today using a small script. The architecture is already designed for it.

The pattern is always the same:

1. Run your tool and capture its structured output
2. Write a script that maps tool output → { phases: [...], categories: {...} }
3. POST to https://api.progress.report/api/publish with your API key

# Run Jest, output JSON
npx jest --json --outputFile=jest-results.json

# Publish checklist + test results together
npx progress-report publish

# Pull Vanta control statuses (read-only API key)
curl https://api.vanta.com/v1/controls?framework=soc2 \
  -H "Authorization: Bearer $VANTA_API_KEY" \
  > vanta-controls.json

# Map Vanta output → compliance phases and POST to progress.report
# (progress.report Vanta adapter — coming soon)
node scripts/vanta-to-progress.mjs --input vanta-controls.json

Progression types on the roadmap

Beyond what exists today, these are the distinct types of progress we plan to support as first-class tabs in the viewer:

Simple, transparent pricing

Start free. Upgrade when you grow. No per-seat fees, no surprise overages.

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://api.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 — Set up your project

In your project directory, run the interactive setup wizard:

npx progress-report init

The wizard prompts for your API key, developer slug, project name, view 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

Your client's progress page URL is determined by the slugs you choose:

https://view.progress.report/{developer}/{project}/{view}

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

Step 3 — Edit your checklist and publish

Open progress.jsonc and define your phases. Then:

npx progress-report publish

── progress.report ────────────────────────
  View     : acme/website-redesign/build
  Artifact : checklist (progression)
  Name     : Acme Corp Website Redesign
  Version  : 0.1.0
  Phases   : 3
  Progress : 2/8 done (1 in-progress, 1 need-you, 0 blocked)
  Publishing checklist… ✓

  Live at: https://view.progress.report/acme/website-redesign/build
  v0.1.0 · 2026-04-08

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 · acme/website-redesign/build ──────────
  Name     : Acme Corp Website Redesign
  Version  : 0.3.0
  Updated  : 2026-04-08

  checklist (progression) — 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/acme/website-redesign/build

progress.config.json

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

{
  "developer":  "acme",
  "project":    "website-redesign",
  "view":       "build",
  "artifact":   "checklist",
  "apiKey":     "pr_live_...",
  "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.

Views & Artifacts

Every progress page is a view — a stable URL you share with a client. A view contains one or more artifacts, each an independently publishable progression. The viewer renders artifacts as tabs; the framework doesn't know or care about "tabs."

URL structure

https://view.progress.report/developer/project/view/artifact

  developer  — your account or org slug
  project    — the project or engagement slug
  view       — the shareable client-facing context (e.g. "build", "compliance")
  artifact   — deep-link to a specific artifact tab (optional)

Navigating to the 3-segment URL loads the full view with all artifact tabs visible. The 4-segment URL deep-links directly to a specific artifact.

// Share with client — shows all tabs
https://view.progress.report/acme/website-redesign/build

// Deep-link to a specific artifact
https://view.progress.report/acme/website-redesign/build/checklist
https://view.progress.report/acme/website-redesign/build/tests
https://view.progress.report/acme/website-redesign/compliance/soc2

Artifact types

Every artifact has a type that controls how the viewer labels statuses. All types use the same underlying phases → tasks → subtasks data structure.

Independent publishing

Each artifact is published separately. Different tools, pipelines, or team members can own different artifacts within the same view — they never overwrite each other.

{
  "developer": "acme",
  "project":   "website-redesign",
  "view":       "build",
  "artifact":   "checklist",
  "type":       "progression",
  "checklist":  "./progress.jsonc",
  // testSpec publishes automatically as the "tests" artifact in the same view
  "testSpec":   "./testspec.jsonc"
}

When you run npx progress-report publish with a config that has both checklist and testSpec, two artifacts are published to the same view:

  Publishing checklist… ✓
  Publishing tests…     ✓

  Live at: https://view.progress.report/acme/website-redesign/build

Each artifact can also be published from a completely separate config — for example, a CI pipeline that only updates the tests artifact without touching the checklist.

API Reference

Base URL: https://api.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"
}

List all views belonging to your account.

Response 200

{
  "views": [
    {
      "developer": "acme",
      "project":   "website-redesign",
      "view":      "build",
      "name":      "Acme Corp Website Redesign",
      "url":       "https://view.progress.report/acme/website-redesign/build"
    }
  ]
}

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

Request body

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

Response 200

{
  "ok":        true,
  "developer": "acme",
  "project":   "website-redesign",
  "view":      "build",
  "url":       "https://view.progress.report/acme/website-redesign/build"
}

Load a complete view — returns metadata and all published artifacts. This is the primary endpoint used by the viewer.

Response 200

{
  "developer":  "acme",
  "project":    "website-redesign",
  "view":        "build",
  "name":        "Acme Corp Website Redesign",
  "client":      { /* branding */ },
  "theme":       { /* colors */ },
  "artifacts": [
    {
      "artifact":   "checklist",
      "type":       "progression",
      "name":       "Build Progress",
      "version":    "0.3.0",
      "updatedAt":  "2026-04-07",
      "phases":     [ /* phases → tasks → subtasks */ ]
    },
    {
      "artifact":   "tests",
      "type":       "testspec",
      "name":       "Unit Tests",
      "phases":     [ /* suites → test cases */ ]
    }
  ]
}

Load a single artifact record directly.

Publish an artifact to a view. Creates the view on first publish; overwrites the artifact on subsequent publishes. Each artifact within a view appears as a tab in the viewer.

Request body

{
  "developer":  "acme",                            // required
  "project":    "website-redesign",               // required
  "view":        "build",                          // required
  "artifact":    "checklist",                      // required
  "type":        "progression",                    // optional — defaults to "progression"
  "name":        "Acme Corp Website Redesign",    // optional — tab display label
  "version":     "0.3.0",                          // optional
  "updatedAt":   "2026-04-07",                     // optional — defaults to today
  "phases": [                                            // required
    {
      "id": "1", "name": "Discovery", "status": "done",
      "tasks": [
        { "id": "1.1", "name": "Requirements", "status": "done", "subtasks": [] }
      ]
    }
  ],
  "client": { "name": "...", "company": "...", "tagline": "..." },  // optional
  "theme":  { "primary": "#1D4ED8", "accent": "#10B981" }           // optional
}

Response 200

{
  "ok":          true,
  "developer":   "acme",
  "project":     "website-redesign",
  "view":         "build",
  "artifact":     "checklist",
  "type":         "progression",
  "version":      "0.3.0",
  "url":          "https://view.progress.report/acme/website-redesign/build",
  "updatedAt":    "2026-04-07"
}

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.

CI/CD Integration

Publish progress automatically on every merge, deploy, or test run. The CLI works anywhere Node.js 18+ runs — GitHub Actions, GitLab CI, CircleCI, Jenkins, or any shell script.

GitHub Actions

Add a step at the end of your workflow to publish after every successful build or test run.

name: Publish progress

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      # Run your tests and capture output
      - name: Run tests
        run: npm test -- --json --outputFile=test-results.json

      # Publish checklist + test results to progress.report
      - name: Publish progress
        run: npx progress-report publish --bump
        env:
          # Store your API key in GitHub → Settings → Secrets
          PR_API_KEY: ${{ secrets.PROGRESS_REPORT_API_KEY }}

GitLab CI

publish-progress:
  stage: deploy
  image: node:20-alpine
  script:
    - npx progress-report publish --bump
  only:
    - main

Direct API call (any environment)

If you can't install Node.js, publish directly with curl:

curl -X POST https://api.progress.report/api/publish \
  -H "Authorization: Bearer $PR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @publish-payload.json

URL Structure

Every progress page follows the same four-segment pattern, making URLs human-readable, brandable, and QR-code friendly.

https://view.progress.report/developer/project/view

https://view.progress.report/developer/project/view/artifact

Slug rules

Each segment must be 1–64 characters: alphanumeric, hyphens, and underscores. Must start with a letter or digit. Slugs are case-sensitive.

✓ Valid slugs
acme  |  my-project  |  website_v2  |  QT-CRCF  |  build

✗ Invalid
-starts-with-dash  |  has spaces  |  has/slash

QR codes

A typical progress URL is 50–70 characters — well within the reliable range for printed QR codes. Use the 3-segment view URL for client-facing materials so the artifact tab structure can evolve without breaking existing codes.

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.

Roadmap

What's shipped, what's in progress, and what's coming next. We build in the open — feature requests welcome at hello@progress.report.

Frequently asked questions

Get help

We're a small team and we respond personally. If something is broken or unclear, reach out — we take it seriously.

Email support

Email hello@progress.report for any question: billing, API behavior, feature requests, or bugs. We aim to respond within one business day.

Bug reports

Found a reproducible bug? Include:

• The exact command you ran (redact your API key)
• The full error output or unexpected response
• Your progress.config.json (redact apiKey)
• Node.js version (node --version)
• CLI version (npx progress-report --version)

Enterprise SLA

Enterprise customers receive a dedicated Slack channel and a 99.9% uptime SLA with 4-hour response time for P1 incidents. Contact us to discuss.

API status

Verify the API is reachable at any time:

curl https://api.progress.report/api/health

{ "ok": true, "service": "progress.report", "version": "1.0.0" }