# SmarterSheet SmarterSheet shows your Smartsheet projects in the browser: a portfolio overview and timeline, your open tasks, a Gantt chart per project with dependency arrows, and an ITM task and hours tracker that stays in sync with your ITM sheet. It runs on your own computer with your own Smartsheet API token. It needs Python and nothing else. Website: . Version 1.1.0. ## 1. What you need - **Python 3.10 or newer.** Nothing else: SmarterSheet uses only Python's standard library, so there is no `pip install`. - Windows / macOS: . On Windows, tick **"Add python.exe to PATH"** in the installer. - Linux: usually there already (`python3 -V`); otherwise `sudo apt install python3` (Debian/Ubuntu), `sudo dnf install python3` (Fedora), `sudo pacman -S python` (Arch). - A Smartsheet account and a Smartsheet **API token**. The setup shows you how to make one (section 3). - An internet connection on first start, to download the program files. After that it also works from a saved copy (section 7). ## 2. Install and start ### Windows and macOS 1. Make a folder, e.g. `Documents\SmarterSheet`. 2. Download [run-smarterSheet.py](run-smarterSheet.py) into it. 3. Double-click it, or open a terminal in that folder and run: ``` python run-smarterSheet.py (Windows; "py run-smarterSheet.py" also works) python3 run-smarterSheet.py (macOS) ``` 4. Answer the setup questions (section 3). Your browser then opens . Keep the window open while you use SmarterSheet. Close it, or press Ctrl+C, to stop. Next time, start it the same way; the setup is not asked again. ### Linux ``` curl -fsSL https://smartersheet.microide.com/install-linux.sh | bash ``` The [installer](install-linux.sh) needs no root. It: 1. checks for Python 3.10+; 2. downloads `run-smarterSheet.py` into `~/.local/share/smartersheet` (choose another folder with `SMARTERSHEET_DIR=/path`); 3. runs the setup in your terminal; 4. adds the command `smartersheet` to `~/.local/bin`; 5. installs and starts a systemd **user** service `smartersheet`, so SmarterSheet runs in the background and starts again after a reboot. Leave this step out with `bash -s -- --no-service`. To keep it running while you are logged out: `sudo loginctl enable-linger $USER`. Useful commands afterwards: ``` smartersheet --setup # change the token, ITM sheets, edit rights, port systemctl --user restart smartersheet # restart the background service journalctl --user -u smartersheet -f # its log ``` You can also skip the installer and run the script directly: `python3 run-smarterSheet.py`. ## 3. The setup (first start, or `--setup`) The setup runs in the terminal window and has four steps. **1. API token.** SmarterSheet explains how to get one: 1. Sign in at . 2. Click your account picture (bottom left), then **Personal Settings…** 3. Choose **API Access** (on some accounts: **Apps & Integrations → API Access**). 4. Click **Generate new access token**, name it `SmarterSheet`, click OK. 5. Copy the token. Smartsheet shows it only once. Paste it at the prompt. The input stays hidden; on some Windows consoles right-click pastes. SmarterSheet checks the token against Smartsheet (US, EU and AU regions are tried), shows who you are signed in as, and stores the token in its database. If the token is refused, it asks again. **2. ITM sheet and archive.** SmarterSheet lists your sheets and looks for **ITM** in their names. Your ITM sheet is usually called ` - ITM`; its archive (where Smartsheet moves completed rows) is usually ` ITM - Archive`. - One candidate: you confirm it (Enter = yes). - Several candidates (e.g. you can also see a colleague's ITM sheet): it lists them with their sheet ids and asks which one is yours, first for the ITM sheet and then for the archive. - None, or not the right one: type the sheet's exact name or its id (from the sheet's URL or File → Properties), or press Enter to skip. With no ITM sheet, the "My ITM tasks" view stays off. **3. Which projects SmarterSheet may edit.** SmarterSheet reads every project it finds (section 4). From the Gantt chart it can also *change* plans. Choose one: - all projects, including ones added later (recommended); - only the projects you pick from a numbered list; - none (read-only). The ITM sheet and archive can still be updated. **4. Port and network.** The page runs on port **5300** unless you choose another. SmarterSheet has no login of its own, so by default only your computer can open it. Answer "yes" to the network question only if you want other computers on your network to reach it. Anyone who can open the page can then use your token. ## 4. What it shows **Projects.** SmarterSheet walks your Smartsheet **Workspaces**. A folder counts as a project when it holds a sheet named **"Project Plan"**, or a single sheet that is not a "META" sheet (older projects name the plan after the project). Folders named *Archive*, *Starter Blueprint* or *Reference*, and everything below them, are skipped. The plan sheet's Gantt columns (start, end, duration, predecessors, % complete, assigned to, status) are found by their Gantt tags or by their usual titles. Views, in the sidebar: - **Overview**: every project with its dates, progress, schedule health and late tasks, plus tiles for errors (e.g. `#UNPARSEABLE` cells) and tasks with no predecessor. Star a project to keep it at the top; the favourites are stored in the database. - **Portfolio timeline**: all projects on one time axis. - **My open tasks**: every task assigned to you, across all projects. - **A project** (click it in the sidebar): a Gantt chart with dependency arrows and a NOW line, the sheet summary, files and comments. Click a task for its details. If edits are allowed on that project, you can also: - change its duration (working days), start date or predecessor lags; Smartsheet recalculates the dates; - add a sub-task, a new predecessor or a next task (links are re-chained so the order holds); - upload a proof (a new version if one with that name exists); - fill empty Predecessors cells from a proposal ("chain in row order", keeping existing dates where it can). - **My ITM tasks** (section 5). **Staying current.** SmarterSheet keeps a copy (snapshot) of your account in its database: - every 60 seconds it asks Smartsheet which sheets changed, and re-reads only those projects; - every 10 minutes it also compares comments and files; - every hour it re-reads everything, which also finds new projects. The first full read takes a few minutes; the page opens by itself when it is done. **Refresh** in the sidebar checks now. **full re-read** reads everything again. ## 5. The ITM tracker ("My ITM tasks") A table of your ITM tasks with one column per day. Click a day cell to set the hours you worked that day: 15-minute steps up to 2 h, then whole hours, at most 8 h. It shows today's and this week's total (Sunday–Saturday), and ranges of 7, 14 or 28 days or custom dates. Weekends and Canadian (Alberta) holidays are shaded. - **New task**: adds a row (Title, Task, Project #, Customer, Complexity, Category, Due date …). The pick-lists come from your sheet's own columns. Project # suggests your Smartsheet projects (an `R&D-1439 …` project appears as `RnD-1439`). - **Complete**: marks a task done and writes Hours, Task Complete and the completion dates to the sheet **at once**. Reopening a task, or adding hours to a completed one, is also written at once. - **Push to Smartsheet**: everything else (new tasks, changed details, hours) is written when you press this button. A small "new" or "↑" marker shows what is waiting. - Every 3 minutes SmarterSheet pulls the sheet. Rows added in Smartsheet appear here. A completion ticked in Smartsheet wins. Hours typed directly into Smartsheet are kept and never counted twice. Rows that Smartsheet moved to the archive stay tracked. ## 6. Files and data Next to `run-smarterSheet.py`: | File / folder | What it is | |---|---| | `smarterSheet_DB.sqlite3` | **Everything SmarterSheet keeps**: your API token, settings, the snapshot of your projects, favourites, ITM tasks and hours, and a log of every change written to Smartsheet (with the old values). Created on first start. **Private: do not share it, e-mail it or commit it anywhere.** | | `smartersheet_app/` | The program files, downloaded from this site and updated on every start (checked by SHA-256). Safe to delete; they are downloaded again. | Smartsheet's API has no read-only token. SmarterSheet itself only sends GET requests, except for the edits you make on the page, and only to the sheets you allowed in the setup. The list of changes it made is at . To revoke SmarterSheet's access completely, delete the token on Smartsheet's API Access page. ## 7. Options ``` python run-smarterSheet.py [options] --setup run the setup again (keeps what you do not change) --setup-only run the setup and exit --port 5301 use another port this time (the setup stores a permanent one) --host 0.0.0.0 let other computers connect this time (no login - careful) --no-browser do not open the browser --update install a newer version without asking --no-update do not check this site for a newer version --db PATH use another database file --log-level INFO more output in the window (DEBUG for even more) ``` **Updates.** On every start the script checks this site's `app/manifest.json` for a newer version. If there is one, it tells you and asks: ``` A newer SmarterSheet is available: 1.2.0 (you have 1.1.0). Update now? [Y]es / [n]ot now / [s]kip this version: ``` - **Yes** downloads the new files (each checked against its SHA-256 sum) and starts the new version. - **Not now** starts your current version; you are asked again next time. - **Skip this version** starts your current version and does not ask again until an even newer version comes out. While SmarterSheet runs, it also checks every 6 hours. When there is a newer version, a blue notice appears in the sidebar of the page, with a **Skip this version** link. When SmarterSheet runs without a terminal (the Linux background service, `pythonw`), it cannot ask: it keeps your version and only shows the notice. Install the update with `smartersheet --update` or `python run-smarterSheet.py --update`, then restart the service (`systemctl --user restart smartersheet`). If the site cannot be reached, your current version starts as usual. The check only downloads the manifest; nothing about you is sent. **No internet / locked-down PC.** Download [smartersheet.zip](smartersheet.zip) or [smartersheet.tar.gz](smartersheet.tar.gz) on another machine. Unpack it, and start it with `python run-smarterSheet.py --no-update`. SmarterSheet still needs to reach `api.smartsheet.com`. **Run it in the background on Windows.** Use `pythonw run-smarterSheet.py --no-browser` from a shortcut in `shell:startup`. Finish the setup once in a normal window first. ## 8. Troubleshooting - **"python" is not found (Windows):** reinstall Python and tick "Add python.exe to PATH", or use `py` instead of `python`. - **Certificate errors on macOS:** run "Install Certificates.command" from the Python folder in Applications. - **"Could not start on port 5300":** another program (or a second SmarterSheet) uses that port. Use `--port 5301`, or change the port permanently with `--setup`. - **"Smartsheet did not accept that token":** make a new one (section 3) and paste the whole token. - **"Smartsheet API error 429":** Smartsheet's rate limit (300 requests per minute). SmarterSheet waits and retries by itself. - **The ITM view says no ITM sheet is chosen:** run `--setup` and pick your sheet in step 2. - **A project is missing:** check that its folder has a "Project Plan" sheet and is not below an Archive / Starter Blueprint / Reference folder. Then press "full re-read". - **Start again from scratch:** stop SmarterSheet and delete `smarterSheet_DB.sqlite3`. This also deletes your local ITM hours that were not pushed yet. ## 9. Changes - **1.1.0** (2026-11-04): you are asked before an update is installed (yes / not now / skip this version), and the page shows a notice when a newer version is out. Earlier, the files were replaced silently on every start. - **1.0.0** (2026-11-04): first release. ## 10. Uninstall - Windows / macOS: delete the folder. To end SmarterSheet's access, also delete the token in Smartsheet. - Linux (installer): ``` systemctl --user disable --now smartersheet rm ~/.config/systemd/user/smartersheet.service ~/.local/bin/smartersheet rm -r ~/.local/share/smartersheet # deletes the database too ``` SmarterSheet is not affiliated with Smartsheet Inc. "Smartsheet" is a trademark of Smartsheet Inc.