Quick Guide: dspot-trello-gantt

This document summarizes the real installation and publishing flow we validated, including common errors and how to fix them.

Index

• What this project does
• 1) Install and validate the CLI
• 2) Initialize a local project
• 3) Configure Trello in .env
• 4) Generate a local report
• 5) Day-off indicators
• 6) Task dependencies
• 7) Google Cloud
• 8) Google Scripts
• 9) Publish
• Commands
• Common errors (and fixes)
• Operational recommendation

What this project does

• Reads cards from a Trello board using the Trello API.
• Converts board data into Mermaid Gantt tasks.
• Generates a standalone HTML report that can be shared locally.
• Optionally overlays employee day-off indicators loaded from a Google Sheets timesheet.
• Optionally publishes the report to Google Apps Script using a stable URL.

1) Install and validate the CLI

Requirement: Node.js >=18 (recommended LTS versions: 18, 20, or newer).

node -v
npm -v
npm install -g dspot-trello-gantt
trello-gantt-js --help

If trello-gantt-js --help returns output, the global installation is correct.

To update the CLI later, run:

npm install -g dspot-trello-gantt@latest

2) Initialize a local project

mkdir trello-gantt-report
cd trello-gantt-report
trello-gantt-js init

This creates the base .env file.

3) Configure Trello in .env

In .env:

TRELLO_API_KEY=...
TRELLO_API_TOKEN=...
GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
GANTT_LISTS=Backlog,To Do,Doing,Done
GANTT_GROUP_LISTS=Milestone 1,Milestone 2,Sprint 1,Sprint 2
GANTT_TITLE=Project Gantt Chart
GANTT_MIN_TIMELINE_DAYS=14
GANTT_RENDERER=mermaid
GANTT_OUTPUT=output/gantt.html
GANTT_TIMESTAMP_OUTPUT=false

How to get Trello credentials:

1. Open https://trello.com/app-key while logged into the Trello account that has access to your board.
2. Copy your API Key and use it as TRELLO_API_KEY.
3. On the same page, click the token link/button (usually "Token") to generate a user token.
4. Authorize access and copy the generated token.
5. Use that value as TRELLO_API_TOKEN.
6. Use your board URL (or board ID) as GANTT_BOARD_ID.

How to set GANTT_GROUP_LISTS:

1. Open your Trello board.
2. Use Trello labels in your cards to mark milestones or sprints (for example Milestone 1, Milestone 2, Sprint 1).
   • Milestone labels must start with Milestone (including the trailing space), e.g. Milestone 1.
   • Sprint labels must start with Sprint (including the trailing space), e.g. Sprint 1.
   • If a card has both a milestone and a sprint label, the milestone label takes priority.
3. If you want to restrict groups to a specific subset, set GANTT_GROUP_LISTS as a comma-separated allowlist (same spelling as label/list names in Trello).
4. If GANTT_GROUP_LISTS is empty, group detection is automatic and includes all milestone and sprint labels by default.
5. Cards with no matching label are grouped under Unassigned, which always appears last in the chart.

How to get GANTT_LISTS:

1. Open your Trello board and review the list names.
2. Choose which lists should be included in the Gantt output.
3. Add those list names in .env as a comma-separated value (for example Backlog,To Do,Doing,Done).
4. Leave it empty to include all lists.

Progress percentage from Trello cards:

• The chart reads each card progress from a ## Progress section in the card description.
• Example:
  • ## Progress
  • 72
• Accepted values are 0 to 100 (the % symbol is optional). If the section is missing, progress defaults to 0%.

What GANTT_TIMESTAMP_OUTPUT is for:

• Controls whether each generated file uses a unique timestamped name.
• false (default): writes to a stable filename (for example gantt.html) and replaces it on each run.
• true: creates versioned files (for example gantt-YYYYMMDDTHHMMSSZ.html), useful for keeping history and avoiding overwrites.

What GANTT_TITLE is for:

• Sets the title shown in the generated Gantt chart.
• Use it to display a project/client-specific name (for example Website Migration - Q2).
• If not set, the tool uses its default chart title.

What GANTT_MIN_TIMELINE_DAYS is for:

• Defines the minimum number of days shown on the chart timeline.
• Useful when your tasks are concentrated in a short range and long titles make the chart look crowded.
• Default is 14 (2 weeks). Use values like 21 or 30 for more horizontal spacing.
• Must be an integer >= 1; invalid values fall back to default.

What GANTT_OUTPUT is for:

• Defines where the generated HTML file is saved.
• Use it when you want the report in a specific folder or filename (for example output/gantt.html).
• If not set, the tool uses its default output path.

What GANTT_RENDERER is for:

• Selects which timeline renderer is used in the generated HTML.
• mermaid (default): keeps the current Mermaid-based Gantt behavior.
• html: uses a native HTML timeline renderer designed for custom UI evolution.
• You can override this value from CLI with --renderer mermaid or --renderer html.

4) Generate a local report

trello-gantt-js generate

Optional with timestamp:

trello-gantt-js generate --timestamp-output

Optional with HTML renderer:

trello-gantt-js generate --renderer html

5) Day-off indicators

Day-off indicators are only rendered when GANTT_RENDERER=html. They show a grey overlay on each day a given assignee is off, and display a tooltip with the day-off type and the assignee's full name on hover.

Enabling day-off data

Add one of the following to your .env:

# Option A: live fetch from Google Sheets (requires OAuth on first use)
GANTT_DAYOFF_SHEET_ID=your_spreadsheet_id

# Option B: pre-generated JSON file (takes priority over the sheet ID)
GANTT_DAYOFF_JSON=path/to/dayoff.json

The spreadsheet must contain one or more tabs with "timesheet" in their name. Each tab is expected to follow the standard DSpot timesheet layout (employee names in the first column, day-off codes in the day columns).

Supported day-off codes:

| Code | Meaning | |------|---------| | H | Public Holiday | | PH | Pre Holiday | | V | Vacation | | U | Unpaid leave | | I | Important Event | | Sick | Sick leave | | ML | Maternity / Medical leave | | CV | Carried Over Vacation |

OAuth for Google Sheets

The first time GANTT_DAYOFF_SHEET_ID is set, the tool opens a browser for Google OAuth and saves the token at credentials/dayoff-token.json. Subsequent runs reuse that token automatically.

The same credentials/google_oauth_client.json used for publish is reused here. No additional Google Cloud setup is required if you have already completed 7) Google Cloud.

Using the day-off overlay in the chart

• The Day Off section in the sidebar legend lists all supported types.
• Use the Show toggle next to the legend heading to display or hide the overlays (hidden by default).
• Hover over any overlay to see a tooltip with the day-off code and the assignee's full name.

6) Task dependencies

Task dependencies let you define which cards must finish before another card can start. No .env configuration is needed — dependencies are read directly from Trello card attachments.

How to set up a dependency

1. Open the dependent card in Trello (the one that should start after another finishes).
2. Click Attachment and paste the URL of the predecessor card (for example https://trello.com/c/abc123/my-task).
3. Repeat for each predecessor the card depends on.

The tool reads all non-file attachments on each card, extracts Trello card URLs, and resolves them to task IDs automatically.

How dependencies appear in the chart

• Mermaid renderer: dependent tasks use Mermaid's after syntax, so their start date shifts to respect the predecessor's end date.
• HTML renderer: a curved arrow is drawn from the end of the predecessor bar to the start of the dependent bar.

A card can depend on multiple predecessors — attach as many card URLs as needed.

Only attachments that are Trello card URLs are treated as dependencies. File uploads and external URLs are ignored.

7) Google Cloud

Also (Google Cloud OAuth setup for publish):

1. Create a Google Cloud project (or select the one you will use).
2. Configure the OAuth consent screen (APIs & Services → OAuth consent screen) based on your audience:
   • External projects (clients/outside users): use External.
   • Internal-only projects (DSpot organization only): use Internal.
   • Important: keep Google Cloud audience and Apps Script deployment access aligned (for example, External + Anyone with Google account, or Internal + Anyone within DSpot Developers).
3. Enable Apps Script API in that project (script.googleapis.com).
4. Create an OAuth Client for a desktop application.
   • Use Desktop app as the application type.
5. Download the OAuth Client JSON.
6. Save it in your local project at: credentials/google_oauth_client.json

Note for future projects: If you've already set up a previous project, you can continue using the same Google Cloud OAuth client and do not need to configure everything from scratch. In the simplest workflow, you only need to create a new Apps Script project.

8) Google Scripts

Make sure Apps Script API is enabled in the Apps Script user settings (allow third-party apps): https://script.google.com/home/usersettings.

In .env:

GAPPS_SCRIPT_ID=...
GAPPS_DEPLOYMENT_ID=...
GAPPS_ALLOWED_EMAILS=

GAPPS_ALLOWED_EMAILS is the comma-separated list of email addresses allowed to access the published Gantt web app. If left empty, access is public (based on your web app deployment settings).

How to find GAPPS_SCRIPT_ID:

• If you don't already have an Apps Script project, create a new one.
• Open your Apps Script project.
• Go to Project Settings (gear icon).
• Copy the value shown as Script ID.
• Paste it into .env as GAPPS_SCRIPT_ID.

How to find GAPPS_DEPLOYMENT_ID:

• Open your Apps Script project.
• Click Deploy -> Manage deployments.
• If no deployment exists yet, create one first:
  • Click New deployment.
  • Select type Web app.
  • Recommended settings (for this tool):
    • Description: (Enter a name that helps you associate this deployment with your Gantt charts, for example, the project or client name)
    • Execute as: User accessing the web app
    • Who has access:
      • External projects: Anyone with Google account
      • Internal-only projects: Anyone within Dspot Developers (or your Workspace org equivalent)
  • Review the settings above (Description / Who has access, if applicable) and click Deploy.
• After deployment is created/updated, copy the value shown as Deployment ID.
• Paste it into .env as GAPPS_DEPLOYMENT_ID.

9) Publish

trello-gantt-js publish

On the first run, Google OAuth opens and credentials/token.json is saved.

Commands

• trello-gantt-js init: creates a base .env template in the current folder.
• trello-gantt-js generate: generates a local HTML Gantt report.
• trello-gantt-js generate --renderer html: generates the report with native HTML timeline renderer.
• trello-gantt-js generate --timestamp-output: generates a versioned output filename with UTC timestamp.
• trello-gantt-js publish: generates and uploads the report to Google Apps Script.
• trello-gantt-js version (or trello-gantt-js --version / trello-gantt-js -V): prints the installed CLI version.
• trello-gantt-js --help: shows CLI help and available options.

Common errors (and fixes)

Error 403: access_denied on Google screen

Typical message: "only be accessed by developer-approved testers".

Most likely cause:

• The OAuth app is in Testing mode and the email is not in Test users.

Fix:

1. Go to Google Cloud Console -> OAuth consent screen -> Test users.
2. Add the user email (for example [email protected]).
3. Verify google_oauth_client.json belongs to that same OAuth project.
4. Delete credentials/token.json and retry trello-gantt-js publish.

Important: Giving IAM "Editor" in Google Cloud does not replace the Test users list in OAuth consent screen.

OAuth: accounts outside the company cannot sign in

This is expected when the OAuth audience is Internal: only your Workspace org can sign in. If you need external users, switch the consent screen to External (or create a new OAuth project with External audience) and make sure Apps Script "Who has access" is also configured for external access. While the app is in Testing, add users under Test users, or complete verification for production.

Error: The caller does not have permission

If this appears during Apps Script upload:

• Check that GAPPS_SCRIPT_ID and GAPPS_DEPLOYMENT_ID are correct and from the same project.
• Share the Apps Script project with the user as Editor.
• Delete credentials/token.json to re-authenticate with the correct account.

Error: Only users in the same domain as the script owner may deploy this script

Cause:

• Google Apps Script/Workspace domain restriction for deployments.

What this means:

• Users outside the owner's domain may edit, but cannot necessarily deploy.

Options:

• Always publish with the script owner account.
• Create/transfer the script to an account in the same domain as the user who will publish.
• Ask the Google Workspace admin to review deployment/sharing policies.

Operational recommendation

If you have external users (for example @gmail.com accounts) and your script is corporate-owned, use this flow:

1. External users generate locally (generate).
2. Only the owner account (or same-domain account) runs publish.

This avoids domain policy deployment blocks.