taskforce-cli

A command-line client for Task Force — create, update, and complete tasks and projects from the terminal, designed to be used by both developers and AI coding agents.

Every command prints a single, filtered JSON object (or array) to stdout and nothing else on success. On failure, it prints {"error": "..."} to stderr and exits non-zero. This makes commands easy to chain — see skills/taskforce/SKILL.md for the full output schemas and chaining patterns.

Install

From npm

npm install -g @iamt12e/taskforce-cli

This installs both taskforce (talks to the production Task Force instance by default) and taskforce-dev (defaults to a local instance at http://127.0.0.1:8047/api, with its own separate config — handy for developing/testing against a local Task Force without touching your real account).

From source

npm install
npm run build:all   # builds dist/index.js (prod) and dist/index.dev.js (dev)
npm link            # installs `taskforce` and `taskforce-dev` globally

Either binary's default API URL can be overridden at runtime with --api-url, the TASKFORCE_API_URL env var, or by saving a different apiUrl in the config file.

To change the defaults baked into a build (e.g. point taskforce-dev at a different local instance), copy .env.example to .env and set TASKFORCE_PROD_API_URL / TASKFORCE_DEV_API_URL, then rebuild. .env is gitignored, so each dev can point their build at their own instance.

Quick start

# 1. Authenticate (stores a token in ~/.config/taskforce/config.json)
taskforce login --email [email protected] --password '...'

# 2. Link the current repo to a Task Force project
taskforce init --project-id 5
# ...or create a new project and link it in one step
taskforce init --create --name "My Project"

# 3. Create a task
taskforce task create --title "Fix auth refresh race" --description "..."

# 4. Log already-completed work (create + complete in one step)
taskforce task create --title "Add CSV export" --description "..." --done

# 5. List, show, update, complete
taskforce task list
taskforce task show 123
taskforce task update 123 --status "In Progress"
taskforce task complete 123

Commands

| Command | Description | | --- | --- | | taskforce login [--email] [--password] [--api-url] | Authenticate and store a token | | taskforce logout | Revoke and clear the stored token | | taskforce whoami | Show the authenticated user | | taskforce init [--project-id <id>] [--create --name <name>] | Link the current directory to a project (.taskforce.json) | | taskforce project list | List projects | | taskforce project create --name <name> [--description] [--product] | Create a project | | taskforce task create --title <t> [--description] [--status] [--project <id>] [--done] | Create a task (--done also marks it complete) | | taskforce task update <id\|-> [--title] [--description] [--status] [--project <id>] | Update a task | | taskforce task complete <id\|-> | Mark a task complete | | taskforce task show <id\|-> | Show a task | | taskforce task list [--project <id>] [--status] [--mine] [--all] | List all tasks (across all pages) | | taskforce task statuses | List valid task status values |

<id|-> means: pass a numeric task id, or - to read a JSON object (with an id field) from stdin — e.g. taskforce task create --title "..." | taskforce task complete -.

Configuration

• Global config: ~/.config/taskforce/config.json (or taskforce-dev for the dev build) — { apiUrl, token, user }.
• Per-project link: .taskforce.json in the repo root — { projectId, projectName }, written by taskforce init. Commit this so the whole team (and their agents) log tasks against the same Task Force project.
• Env var overrides: TASKFORCE_API_URL, TASKFORCE_TOKEN, and (for login) TASKFORCE_EMAIL / TASKFORCE_PASSWORD.

See docs/configuration.md for the full picture (file locations, build-time .env overrides, resolution order).

Security

The Sanctum API token is stored in plaintext in the global config file above. The CLI creates that file with 0600 permissions (owner read/write only) and the containing directory with 0700, and re-applies 0600 on every login/logout. There's no OS keychain integration — run taskforce logout when done with a session, or use TASKFORCE_TOKEN to avoid persisting a token to disk at all (useful for CI/agents). Details in docs/configuration.md.

Agent skill

skills/taskforce/ contains a portable agent skill that teaches AI coding agents when and how to use this CLI — primarily, logging completed work as a task right after finishing it. Install it into any project with:

npx skills add https://github.com/tanaka-mambinge/taskforce-cli/tree/main/skills

Or copy the skills/taskforce/ directory into the project's skills folder manually.

OpenCode commands

This repo also ships OpenCode slash commands under commands/opencode/ and a CLI installer:

taskforce opencode install

That installs into ./.opencode/commands/. Use --global to install into ~/.config/opencode/commands/ instead. It prints a short confirmation, like login.

The raw files live under commands/opencode/:

• /tf-task - create a new Task Force task
• /tf-task-done - create a task and mark it complete
• /tf-task-complete - mark an existing task complete
• /tf-project - create a new Task Force project

Restart OpenCode after install.

Docs

• docs/configuration.md — config files, env vars, build-time .env overrides, security, resolution order
• docs/local-development.md — building both binaries and walking through the full CLI flow against a local instance
• docs/troubleshooting.md — common errors and known local-DB issues