# AX Check: docs.pergola.cloud
Checked 2026-09-25.

Pergola docs get agents to a working quickstart fast
17 of 23 checklist items pass: llms.txt, CLI install, API spec and MCP docs are all in place. Pricing page itself wasn't crawled here.

## Onboarding needs a login

## Coding sessions
All three independent sessions completed and reported pricing, but landed on different answers: two found paid tiers (Starter/Power User/Enterprise with usage fees and a 14-day trial), while one described the product as a free, self-hosted open-source library with no paid tiers.

### DeepSeek V4 Pro
[View public run](https://agents.withgauge.com/p/runs/916db2ff-51e1-43ba-ab91-7e2dd8a0d39f) · [Read transcript](https://www.ax-check.com/docs.pergola.cloud/sessions/deepseek.json)
Final output gives concrete plan pricing (Starter €0.99/mo, Power User €29.99/mo, Enterprise custom), usage-based assumptions (CPU/memory/storage/build rates), stage-type costs, and the 14-day trial, all scraped verbatim from pergola.cloud/pricing (seq 152-186).
#### End-to-end onboarding
- **Onboarding needs a login**: Agent downloaded the real Pergola CLI (v2.3.1) and hit the actual hosted API (api.pergola.cloud, auth.pergola.cloud), but every authenticated path required a human to complete a browser-based device-code login. No credentials were available in the sandbox, the device-code flow timed out unattended, and no authenticated operation (create project, deploy, etc.) was ever completed. The agent stopped and reported the blocker rather than fabricating success.
  Event 264:

  ```text
  HTTP/2 401
  ```
  Event 269:

  ```text
  ERROR   You are not logged in. Please login first.
  To log in, please open the following URL in your browser and make sure it displays the code BLBF-RPQD:
  
      https://auth.pergola.cloud/device?user_code=BLBF-RPQD
  ```
  Event 269:

  ```text
  ERROR   Login cancelled, please try again.
  ```
  Event 289:

  ```text
  No api keys or credentials exist in this environment.
  ```

#### Hallucinated URLs
None identified in this transcript.

#### Blockers
- **Authenticated login wall blocks any real deploy**: Product behavior, not agent error: every Pergola API/CLI action (even local manifest validation) requires an authenticated session, and the only login method is an interactive device-code flow needing a human browser. The sandbox has no credentials, so the CLI login attempt exhausted its wait and cancelled.
  Event 269:

  ```text
  To log in, please open the following URL in your browser and make sure it displays the code BLBF-RPQD:
  
      https://auth.pergola.cloud/device?user_code=BLBF-RPQD
  ```
  Event 269:

  ```text
  ERROR   Login cancelled, please try again.
  ```
- **No anonymous or sandbox API access for verification**: Product behavior: hitting the hosted REST API root without a token returns 401 with a Bearer challenge, confirming there's no read-only or trial path to inspect real resources without first creating an account.
  Event 264:

  ```text
  HTTP/2 401 
  date: Fri, 25 Sep 2026 12:39:26 GMT
  content-length: 0
  vary: Origin
  ...
  www-authenticate: Bearer
  ```
- **Search-engine scraping largely unproductive (test-environment friction)**: Test environment limitation, not a product issue: DuckDuckGo/Bing/Mojeek results were dominated by unrelated 'pergola' patio-furniture SEO content and bot-challenge pages, forcing many detours before the agent found the real product via GitHub org search.
  Event 69:

  ```text
  Pergolas - The Home DepotGet free shipping on qualified Pergolas products
  ```
  Event 132:

  ```text
  action="//duckduckgo.com/anomaly.js?sv=REDACTED&cc=botnet
  ```

#### Suggested Changes
- **Add a non-interactive Access Key path to the quickstart page**: On docs/gettingstarted and docs/cli/, the Getting Started flow only documents the interactive `pergola login --endpoint <URL>` device-code flow; the Access Key docs (docs/operations/accesskeys) are a separate page found later. Surface the Access Key creation/usage steps directly in Getting Started so first-time non-interactive/agent users can validate a manifest and hit the API without a browser. Verify by running `pergola validate manifest pergola.yaml --access-key '<id>:<secret>'` immediately after signup, with no browser step.
  Event 252:

  ```text
  ERROR   Cannot reach endpoint. Please provide a valid API endpoint URL
  ```
  Event 269:

  ```text
  ERROR   You are not logged in. Please login first.
  ```

### Kimi K3
[View public run](https://agents.withgauge.com/p/runs/8d967ac5-9b6b-4864-a035-e22a94531ae2) · [Read transcript](https://www.ax-check.com/docs.pergola.cloud/sessions/kimi.json)
Final output gives a full pricing table (Starter/Power User/Enterprise, usage fees) with named assumptions: 14-day free trial, Stripe billing, excl. VAT, EU-only hosting, stage-based fees.
#### End-to-end onboarding
- **Onboarding needs a login**: The agent never attempted to obtain credentials itself or perform any authenticated operation. It explicitly identified that every entry point (UI, CLI, MCP skills) requires a personal Pergola account/login, declined to create one on the user's behalf, and stopped, asking the user to supply an account or access token before it could proceed.
  Event 80:

  ```text
  Account required. Every entry point (UI, CLI, MCP skills) needs a personal Pergola account and login. I don't have credentials, and I won't create an account or start a trial on your behalf without you doing that step.
  ```
  Event 80:

  ```text
  If you want to unblock me: create a Pergola account yourself, then give me an access token (or install the CLI via curl -fsSL https://get.pergo.la/cli/latest/install.sh | bash and authenticate it).
  ```

#### Hallucinated URLs
None identified in this transcript.

#### Blockers
- **No self-service account creation for Pergola**: Product behavior: every Pergola workflow (UI, CLI, MCP agent skills) requires a personal account and login before any project/stage/build can be created. The agent had no credentials and, following its instructions, declined to sign up on the user's behalf, halting before any authenticated action.
  Event 72:

  ```text
  And, of course, you need to have access to a Pergola platform and a personal account.
  ```
  Event 80:

  ```text
  Account required. Every entry point (UI, CLI, MCP skills) needs a personal Pergola account and login. I don't have credentials, and I won't create an account or start a trial on your behalf without you doing that step.
  ```
- **Quickstart workflow is inherently long-running (builds/deploys)**: Test environment constraint self-imposed by the prompt: the user asked the agent to avoid long-running commands or local service stacks. Pergola's only documented getting-started path involves triggering a container Build ("might take a minute or so") and a Deploy step, which the agent judged incompatible with the 'stay light' instruction, so it stopped rather than attempt it.
  Event 72:

  ```text
  Just click Build now It might take a minute or so, but you should see a new succeeded Build.
  ```
  Event 80:

  ```text
  Container builds and deploys are exactly the long-running operations you told me to avoid, and there's no lightweight "call the API and get a result" workflow — the product's whole purpose is builds/deploys.
  ```

#### Suggested Changes
- **Add a lightweight API-only quickstart path for CI-less experimentation**: The only documented Getting Started flow (docs.pergola.cloud/docs/gettingstarted) requires a Git repo, Dockerfile, pergola.yaml manifest, and a Build/Deploy cycle — there is no documented way to just call a hosted API/SDK for a quick request-response example. Consider adding a minimal 'try the API without deploying' path (e.g., a sandbox endpoint or CLI dry-run) and verify by checking whether a new developer can get a response without triggering a build.
  Event 72:

  ```text
  Pergola runs any application ( e.g. from Python, Java, R, Kotlin, C, etc. ) that comes with a valid Dockerfile. It needs to be available in a Git repository.
  ```
  Event 80:

  ```text
  there's no lightweight "call the API and get a result" workflow — the product's whole purpose is builds/deploys.
  ```
- **Clarify discoverability of the marketing/product domain (pergola.cloud) vs. unrelated same-named packages**: The agent spent multiple search rounds ruling out an npm package, a PyPI bioinformatics library, and several unrelated domains (pergola.io, pergola.ai for sale) before finding the actual product at pergola.cloud. Consider ensuring the product's SEO/branding makes pergola.cloud rank clearly above name collisions for 'Pergola developer platform' style searches, and confirm by searching the product name plus 'API' or 'pricing' from a fresh session.
  Event 8:

  ```text
  pergola (0.2.0)
  Available versions: 0.2.0, 0.1.7...
  ```
  Event 34:

  ```text
  pergola.io -> 200 | 
  pergola.dev -> 000 | 
  pergola.app -> 000 | 
  pergola.com -> 502 | 502 Bad Gateway
  pergola.co -> 200 | 
  pergola.cloud -> 200 | Pergola
  pergola.ai -> 200 | pergola.ai for sale | Spaceship.com
  ```

### Qwen 3.8 Max
[View public run](https://agents.withgauge.com/p/runs/c722cd82-f44f-40ac-879c-781a0d599697) · [Read transcript](https://www.ax-check.com/docs.pergola.cloud/sessions/qwen.json)
README.md 'Pricing' section and final output state cost is $0 with explicit basis: GPLv3 open-source library, no paid tiers/metering/API keys, only self-hosted compute cost and copyleft obligations on redistribution.
#### End-to-end onboarding
- **End-to-end onboarding not demonstrated**: Pergola is a local, offline PyPI/GPLv3 library, not a hosted product with credentials or an API. The agent installed it locally (pip install), ran a local CLI/Python script against a locally-generated CSV, and wrote local BED files. No credentials were obtained or used, and no authenticated call to any hosted service occurred. The agent itself concluded there is no hosted product to onboard to.
  Event 142:

  ```text
  rm -rf out && .venv/bin/python examples/behavior_to_bed.py >/dev/null 2>&1 && bash examples/run_cli.sh >/dev/null 2>&1 && ls out out/api out/cli
  ```
  Event 145:

  ```text
  There is **no hosted Pergola product, no cloud API, and no SDK-as-a-service**. Pergola is a GPLv3 open-source Python library on PyPI
  ```

#### Hallucinated URLs
None identified in this transcript.

#### Blockers
- **No hosted product exists for Pergola**: The seed prompt asked to use a hosted product's SDK/API and assess pricing/manageability, but Pergola turned out to be a dormant, local-only open-source library (last released 2019, Pre-Alpha) with no API, dashboard, pricing, or auth. This is a product-scope mismatch, not an agent error or environment failure — the agent correctly identified and reported this rather than fabricating a service.
  Event 133:

  ```text
  There is **no hosted/SaaS product, no API, no auth,
    no dashboard, and no pricing** — see the honest answer at the bottom of this file.
  ```
  Event 145:

  ```text
  The `pergola.crg.eu` web server mentioned in its README dates from 2016 and isn't a usable offering.
  ```
- **Undeclared pybedtools dependency broke first install**: Installing pergola via pip did not pull in pybedtools, causing an import failure on first run. This is a packaging defect in the pergola PyPI wheel metadata, not an agent or environment issue; the agent recovered by installing pybedtools explicitly.
  Event 34:

  ```text
  ModuleNotFoundError: No module named 'pybedtools'
  ```
  Event 129:

  ```text
  pergola's wheel does not declare pybedtools as a dependency,
  # but pergola.tracks imports it at load time -> install it explicitly.
  ```
- **Delimiter and mandatory-field mismatches caused two failed CLI runs**: The CLI defaulted to TAB delimiter and rejected the comma-separated test file, and a mapping file missing the mandatory 'data_value' term threw a ValueError. Both are product validation behavior surfacing an agent configuration mistake in the test data/mapping file, resolved within the same turn by adding '-fs ,' and a data_value column.
  Event 82:

  ```text
  ValueError: Input delimiter does not correspond to delimiter found in file '	'
  ```
  Event 86:

  ```text
  raise ValueError("Input file mandatory fields  are \"start\" and \"data_value\" \n"
  ```

#### Suggested Changes
- **Add pybedtools to pergola's declared dependencies**: In the pergola PyPI package metadata (setup.py/pyproject), add pybedtools as an install_requires entry, since pergola.tracks imports it at load time but pip install pergola currently omits it, causing a ModuleNotFoundError immediately after a clean install. Verify by running 'pip install pergola' in a fresh virtualenv and confirming 'import pergola' succeeds without a separate pybedtools install.
  Event 34:

  ```text
  ModuleNotFoundError: No module named 'pybedtools'
  ```
- **Document the mandatory mapping fields and default delimiter in the quickstart**: Update the pergola README/documentation to state upfront that mapping files must include 'start' and 'data_value' pergola ontology terms, and that the CLI's default field separator is TAB (validated against the input file, with -fs to override). This would have avoided two failed CLI invocations before the correct mapping/separator combination was found.
  Event 86:

  ```text
  ValueError: Input file mandatory fields  are "start" and "data_value" 
  Your current assigned fields are "start","data_types","track"
  TIP: Check your ontology_file
  ```
  Event 82:

  ```text
  ValueError: Input delimiter does not correspond to delimiter found in file '	'
  ```

### Task given to each agent
Help me build a simple example using Pergola. Tell me how pricing works, and briefly tell me whether this product will be easy for you to manage. Let me know if you get blocked. If this product has no developer workflow you can act on, say so plainly and stop. Stay light: use the hosted product through its SDK or API. Do not start local service stacks or wait for long-running commands; if the quickstart requires either, say so plainly and stop.

No product credentials were supplied and no purchases were authorized.

## Score: B · 81/100 (provisional)
Grades come from completed site checks. Coding sessions and skipped checks do not affect the score.

### Clarity
- **Failed** — Homepage answers Markdown requests

  ```text
  Homepage returned text/html even when text/markdown was requested, so no Markdown representation is served.
  ```

- **Pass** — llms.txt provides an actionable documentation index

  ```text
  llms.txt lists quick start, tutorials, reference, operations and agentic sections with linked .md pages.
  ```

- **Pass** — llms.txt provides navigation guidance

  ```text
  llms.txt groups links under Quick Start, Tutorials, Core Concepts, Operations and Agentic DevOps headings.
  ```

- **Pass** — llms.txt mentions offered API, MCP, and skills

  ```text
  llms.txt links the Project Manifest OpenAPI spec, Agent Skills, and an Agentic DevOps/MCP tutorial.
  ```

- **Pass** — A compact guide representation exists

  ```text
  llms.txt and .md pages provide compact Markdown guides for Pergola docs.
  ```

- **Pass** — A focused guide is directly retrievable

  ```text
  gettingstarted.md and pythonhelloworld.md are directly retrievable Markdown guides.
  ```

- **Pass** — Equivalent instructions fit a token budget

  ```text
  gettingstarted.md is 863 tokens, well under the 8000-token budget.
  ```

- **Skipped** — Product-docs links survive format changes

  ```text
  Homepage Markdown unsupported, so link preservation across formats cannot be measured.
  ```

- **Pass** — The compact guide is independently actionable

  ```text
  Getting Started gives concrete steps: create project, stage, manifest, build, deploy.
  ```

- **Pass** — Install and next-step links resolve

  ```text
  Fetched gettingstarted, pythonhelloworld, and llms.txt links all returned 200.
  ```


### Onboarding
- **Pass** — Docs lead to a relevant quickstart

  ```text
  llms.txt and Getting Started lead to a 5-minute quickstart with concrete project, manifest, build steps.
  ```

- **Pass** — Installation commands are extractable

  ```text
  CLI install commands extractable: curl install script, manual binaries, and pergola login setup.
  ```

- **Pass** — Code examples are available without interaction

  ```text
  Quickstart and tutorial show inline code blocks for Python, Dockerfile, pergola.yaml without interaction.
  ```

- **Pass** — Prerequisites and auth boundaries are explicit

  ```text
  Prerequisites (Docker, Git, account) and auth boundaries (login, endpoint, access keys) are explicit.
  ```


### Pricing
- **Skipped** — Pricing is readable without interaction

  ```text
  No pricing page was fetched; only the docs homepage is available.
  ```

- **Skipped** — Prices are stated, not gated

  ```text
  No pricing page was fetched; only the docs homepage is available.
  ```

- **Skipped** — Pricing units and limits are explicit

  ```text
  No pricing page was fetched; only the docs homepage is available.
  ```

- **Pass** — Agents identify pricing and its assumptions

  ```text
  3 of 3 sessions were judged on pricing; 0 fell short. DeepSeek V4 Pro: Final output gives concrete plan pricing (Starter €0.99/mo, Power User €29.99/mo, Enterprise custom), usage-based assumptions (CPU/memory/storage/build rates), stage-type costs, and the 14-day trial, all scraped verbatim from pergola.cloud/pricing (seq 152-186). Kimi K3: Final output gives a full pricing table (Starter/Power User/Enterprise, usage fees) with named assumptions: 14-day free trial, Stripe billing, excl. VAT, EU-only hosting, stage-based fees. Qwen 3.8 Max: README.md 'Pricing' section and final output state cost is $0 with explicit basis: GPLv3 open-source library, no paid tiers/metering/API keys, only self-hosted compute cost and copyleft obligations on redistribution. This behavioural item does not affect the fast grade.
  ```


### Activation
- **Pass** — An API reference or OpenAPI spec is reachable

  ```text
  OpenAPI 3.0.4 spec for the Project Manifest is served at /pergola_project_manifest_spec.yaml.
  ```

- **Pass** — An MCP server is documented and well-formed

  ```text
  CLI docs document `pergola mcp serve` over stdio with client config and login requirement.
  ```

- **Pass** — A CLI install path is documented

  ```text
  CLI install script and manual binary downloads for Linux, macOS and Windows are documented.
  ```

- **Skipped** — SDK packages resolve on their registries

  ```text
  No registry lookup for a Pergola SDK or packaged CLI package was supplied.
  ```

- **Pass** — Agent skills are published

  ```text
  Pergola Skills repo publishes pergola-mcp, pergola-cli and pergola-manifest skills with install instructions.
  ```



[Full report data](https://www.ax-check.com/docs.pergola.cloud/report.json)