Tracklify CLI — Local Debug Guide

Run and test the Tracklify CLI locally (without compiling or publishing to npm). This guide also explains how the CLI stores your personal token separately for local vs production use.

Prerequisites

• Node.js 16+ installed
• Tracklify backend reachable:
  • Production: https://ws1.tracklify.com (default)
  • Local dev: http://tracklify.localhost:3102 (requires your local stack running)
• A CLI secret token from Tracklify:
  • Production UI: https://web.tracklify.com/get-cli/
  • Local UI: http://web.tracklify.localhost:8080/get-cli/

Project layout

This folder (npm-cli) contains the CLI entry tracklify.js. The package.json already maps the binary name tracklify to this file.

npm-cli/
  ├─ tracklify.js     # CLI entry point
  └─ package.json     # exposes `tracklify` bin

How secrets are stored

The CLI keeps your secret in your home directory under ~/.tracklify/:

• Production (default): ~/.tracklify/key
• Local dev (--local): ~/.tracklify/key_local

This separation lets you use different tokens for production and local stacks without overwriting each other.

Run locally without publishing

You have two easy options.

Option A — Run directly with Node

From the repo root:

# Show help
node npm-cli/tracklify.js --help

# Log in (prod)
node npm-cli/tracklify.js login <SECRET>

# Log in (local) — stores token in ~/.tracklify/key_local and uses local API
node npm-cli/tracklify.js login <SECRET> --local

# Print current-task branch name (prod)
node npm-cli/tracklify.js branch

# Print current-task branch name (local)
node npm-cli/tracklify.js branch --local

# Print current-task commit suffix (prod)
node npm-cli/tracklify.js task

# Print current-task commit suffix (local)
node npm-cli/tracklify.js task --local

Option B — Use npm link (optional)

If you prefer to use the tracklify command directly without node prefix:

cd npm-cli
npm link

# Then anywhere on your machine you can run:
tracklify --help
tracklify login <SECRET>
tracklify login <SECRET> --local
tracklify branch
tracklify branch --local
tracklify task
tracklify task --local

To remove the link later:

cd npm-cli
npm unlink -g

Commands and behavior

• login <secret> [--local]
  • Saves your token to ~/.tracklify/key (prod) or ~/.tracklify/key_local (local).
  • If --local is provided, subsequent commands with --local talk to http://tracklify.localhost:3102.
• branch [--local]
  • Prints the suggested Git branch for your currently tracked task.
• task [--local]
  • Prints the <project>/<taskHid>/<taskSlug> suffix for commit messages.

Examples

# Create a new branch for the current task (prod)
git checkout -b $(node npm-cli/tracklify.js branch)

# Same, but against your local Tracklify stack
git checkout -b $(node npm-cli/tracklify.js branch --local)

# Add task suffix to commit message (prod)
git commit -m "my text $(node npm-cli/tracklify.js task)"

# Local stack variant
git commit -m "my text $(node npm-cli/tracklify.js task --local)"

Where do I get the secret?

• Production: open the Tracklify web app → user menu → "Get CLI" → copy your token.
• Local dev: open http://web.tracklify.localhost:8080/get-cli/ and copy the local token.

Regenerating the token in the web UI will require you to run the CLI login again.

Troubleshooting

• Not logged in / bad token
  • The CLI prints a helpful message and exits with code 2.
  • Run login again with the correct token (remember to include --local if you’re testing locally).
• No active task
  • The CLI exits with code 3 and tells you you’re not tracking any task. Start tracking a task in Tracklify and retry.
• Other errors
  • The CLI exits with code 1 and prints the error message.

Notes

• --local switches both the API base URL and the secret file (key_local).
• For backward compatibility, if --local is used but key_local isn’t present, the CLI will try falling back to key when reading the token.
• Secrets are stored with 0600 permissions under a 0700 directory for safety.