active-collab-cli

active-collab-cli

Unofficial command-line tool and interactive terminal UI (TUI) for reading and browsing ActiveCollab tasks from self-hosted instances. Supports multi-instance configuration, SQLite-backed token storage, and outputs human-readable or JSON task views.

The application ships as a single self-contained binary (ac) built with Rust (ratatui + crossterm + tokio). No interpreter or runtime is required on the target.

⚠️ Unofficial — not affiliated with ActiveCollab

This is an independent, community-built project. It is not an official ActiveCollab product and is not affiliated with, endorsed by, sponsored by, or supported by ActiveCollab or A51 d.o.o. "ActiveCollab" is a trademark of its respective owner and is used here only to describe compatibility with the ActiveCollab REST API of your own self-hosted instance. This tool stores no credentials beyond a local API token, sends that token only to your configured host, and is provided "as is", without warranty. Use at your own risk.

---

Screenshot

Interactive TUI — the task-detail view (project, status, description, assets). The data shown is fictional; no real instance or client data is depicted.

---

Quickstart

From zero to your first task in three steps:

# 1 · Install (macOS / Linux — Windows: see the PowerShell one-liner below)
curl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.sh | sh

# 2 · Register your self-hosted ActiveCollab instance.
#     Prompts once for your password to exchange an API token — the password is never stored.
ac setup add --name collab --url https://collab.example.com --email you@example.com

# 3 · List the open tasks assigned to you
ac mine

Then, day to day:

ac                  # the task for your current git branch (e.g. feature/665-75159)
ac get 665/75159    # a specific task by short form or full URL
ac browse           # full interactive TUI: projects → tasks → detail → assets
ac mine --json      # machine-readable output for scripts and agents

New here? ac setup add walks you through it interactively if you omit the flags. See Usage for every command and flag.

---

Install

macOS / Linux (curl one-liner)

curl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.sh | sh

The script downloads the pre-built active-collab binary for your platform from the latest GitHub Release and places it on your PATH, next to an ac symlink — the short command used throughout this README and by the agent skill. An ac left by an older install is replaced; an ac belonging to another program is kept, with a warning. macOS ships its own /usr/sbin/ac (login accounting), so the installer also warns when that one still wins your PATH lookup.

Windows (PowerShell one-liner)

irm https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.ps1 | iex

Installs active-collab.exe plus an ac.cmd shim, so both active-collab and ac work from cmd and PowerShell.

Manual download

Download the pre-built binary for your platform from the Releases page, place it on your PATH, and make it executable (chmod +x active-collab on Unix). Add the short alias yourself: ln -s active-collab ac (Unix), or an ac.cmd forwarder on Windows.

Platform	Asset
Linux x86_64	active-collab-linux-x86_64
macOS x86_64 (Intel)	active-collab-macos-x86_64
macOS arm64 (Apple Silicon)	active-collab-macos-arm64
Windows x86_64	active-collab-windows-x86_64.exe

Build from source (Docker required)

No local Rust toolchain needed. The crate is at the repo root; Docker provides the build environment.

# Development build
docker compose run --rm dev cargo build

# Release binary (placed in target/release/ac)
docker compose build
docker compose run --rm build

That binary is a Linux build. make install therefore only accepts a Linux host and refuses elsewhere; on macOS use make install-native (needs a host Rust toolchain) or the release installer above.

---

Usage

Setup — manage instances

# Register an ActiveCollab instance (interactive wizard prompts for missing fields)
ac setup add
ac setup add --name collab --url https://collab.example.com --email me@example.com
# Password is always entered hidden via a prompt — never passed as a flag.

# List configured instances (tokens never shown)
ac setup list

# Remove an instance and its cached tasks
ac setup remove --name collab

# Test connectivity to all (or one) configured instance
ac setup test
ac setup test --name collab

# Show the current display language
ac setup language

# Set the display language (persists to SQLite; survives across invocations)
ac setup language en
ac setup language pt_BR

get — fetch a task by URL or short form

ac get 665/75159
ac get https://collab.example.com/projects/665/tasks/75159

current — fetch the task from the current git branch

Branch must match (feature|hotfix|fix)/PROJECT_ID-TASK_ID (e.g. feature/665-75159).

ac current

mine — list open tasks assigned to you

ac mine
ac list          # alias

When run in a terminal (TTY), mine opens an interactive arrow-key list of your open tasks aggregated across all configured instances. Select a task to view its detail or open/download its assets. When output is piped or redirected (non-TTY), mine falls back to a plain table suitable for scripts.

browse — interactive TUI

Arrow-key terminal browser for your open tasks. Navigate projects → tasks → task detail, then open/download the task's assets.

ac browse
ac browse --instance collab   # required when >1 instance configured

The TUI uses ratatui for layout and crossterm for input, giving consistent mouse click, scroll, and keyboard behavior on Linux, macOS, and Windows. It shows a loading indicator during fetches and guards against duplicate in-flight refresh requests (single-flight).

The task detail view shows:

• Meta table — a two-column table listing Task, Project, Title, Status, Assignee, Start, Due, Estimate, and Logged.
• Description — the task body; falls back to (no description) when empty.
• Artifacts panel — lists each image / attachment / link as [n] name with its URL. Press 1–9 to open the matching artifact in your browser.
• Comments — one panel per comment (author · date as the panel title).

The detail view scrolls vertically when content exceeds the screen. The TUI adapts to terminal resize events and guards against too-small terminals without crashing. The footer shows key-cap style hints ([key] action).

Each task you open is written to the local SQLite ticket_cache keyed by instance name; re-opening the same task is instant and offline-tolerant. Press r inside the detail view to bypass the cache and re-fetch from the API.

Key bindings

Screen	Keys
Projects / Tasks lists	↑/↓ or k/j move · Enter select · q quit · b back · s settings
Task detail	↑/↓ or k/j scroll · PgUp/PgDn page · a assets · r refresh · 1–9 open artifact · q/b back
Settings	↑/↓ or k/j move · Enter select · q/b back
Assets	↑/↓ or k/j move · o open in browser · d download · q/b back

Settings screen — press [s] from any list screen to open the Settings panel. It offers two pickers:

• Language — choose en (English) or pt_BR (Portuguese (Brazil)). The selection persists to SQLite and takes effect immediately without restarting.

• Active instance — choose which configured instance browse uses by default when you have more than one. The selection persists to SQLite.

• Assets — image, attachment, and link URLs extracted from the task body, comments, and attachments. o opens the URL in your browser; d downloads it. The X-Angie-AuthApiToken header is attached only when the asset URL's scheme and host match the configured instance — foreign hosts are fetched without credentials.

Bare-invocation shortcuts

ac 665/75159     # same as: ac get 665/75159
ac               # same as: ac current (when branch matches)

Flags

Flag	Applies to	Effect
--instance NAME	get, current, mine, browse	Force a specific configured instance (required when >1 configured)
--short	get, current	Print PROJECT/TASK<TAB>name only
--no-comments	get, current	Omit the comments section
--json	get, current	Print raw task JSON (always hits the API, bypasses cache)
--refresh	get, current	Bypass the task cache and re-fetch from the API

---

Agent skill

ac ships a self-describing agent skill for the --json read contract, so an LLM coding agent can learn how to read your ActiveCollab tasks non-interactively. The full contract lives in one place — inside the binary — and ac prints it on demand:

ac skill list           # list the available skills
ac skill active-collab  # print the full active-collab contract (schemas, the round-trippable ref, flags)
ac skill                # with one skill registered, prints it directly

Install the skill into your agent harness

Every supported harness loads a small thin pointer whose only job is to tell the agent to run ac skill active-collab. Because the pointer carries no schema, it never goes stale when the --json contract changes — only the binary does. Run the installer from your project root for the harness you use (or all):

curl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness cursor
# or wire up every harness at once:
curl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness all

Harness	Project file (--scope project, default)	User-level file (--scope global)
Claude Code	.claude/skills/active-collab/SKILL.md	~/.claude/skills/active-collab/SKILL.md
pi	.pi/skills/active-collab/SKILL.md	~/.pi/agent/skills/active-collab/SKILL.md
Codex CLI	.codex/skills/active-collab/SKILL.md	~/.codex/skills/active-collab/SKILL.md
OpenCode	.opencode/skills/active-collab/SKILL.md	— (install per-project)
GitHub Copilot	.github/skills/active-collab/SKILL.md	— (install per-project)
Cursor	.cursor/rules/active-collab.mdc	— (install per-project)

Claude Code, OpenCode, and pi can also read .claude/skills/active-collab/SKILL.md directly.

Scope. By default the installer writes into the current project (--scope project); pass --dir <path> to target another project. Use --scope global to install once at the user level so the skill is available in every project:

# install the active-collab pointer once, for every harness that supports a user-level dir
curl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness all --scope global

Global scope supports Claude Code, pi, and Codex (the harnesses with a standard user-level skills directory). OpenCode, Copilot, and Cursor have no such directory, so --scope global reports them as unsupported — install those per-project. Running the installer directly in a terminal (not via curl | sh) prompts for project-vs-global; the piped one-liner stays non-interactive and defaults to project. To install into a specific pi profile, use --scope project --dir ~/.pi/agent-profiles/<name>.

This tool only ever reads your ActiveCollab tasks over the --json contract; the skill grants an agent no write access beyond the CLI commands you already run yourself.

---

Internationalization

The binary ships with English (default) and Brazilian Portuguese (pt_BR) translations for all user-facing output. Translations are embedded at compile time as JSON catalogs — no external files required at runtime.

Durable setting — persist your preferred language to SQLite:

ac setup language pt_BR   # set
ac setup language          # show current

One-off override — the ACTIVE_COLLAB_LANG environment variable overrides the stored setting for a single invocation:

ACTIVE_COLLAB_LANG=pt_BR ac browse

Resolution order: ACTIVE_COLLAB_LANG env var → SQLite setting → en.

The language can also be changed interactively from inside browse — press [s] to open Settings and select a language; the change takes effect immediately without restarting.

---

Configuration

Database path: ~/.config/active-collab/active-collab.db

Override with the ACTIVE_COLLAB_DB environment variable:

ACTIVE_COLLAB_DB=/custom/path/active-collab.db ac get 665/75159

---

Security

• The API token is stored only in the local SQLite database with directory permissions 0700 and file permissions 0600.
• The token is transmitted exclusively via the X-Angie-AuthApiToken HTTP header — never in a URL, never printed, never passed as a process argument.
• The password is never stored. Only the token returned from the issue-token endpoint is persisted.
• The token is sent only to the configured instance's own host. Requests to asset URLs on other hosts carry no token.

---

Exit codes

Code	Meaning
0	Success
1	Task not found / HTTP error / parse error
2	Usage error, unknown instance, no instances configured, branch mismatch

---

Development

# Run all tests (unit + integration, including comment-policy gate)
docker compose run --rm dev cargo test

# Run only the comment-policy gate
docker compose run --rm dev cargo test --test comment_policy

# Lint
docker compose run --rm dev cargo clippy -- -D warnings

# Format check
docker compose run --rm dev cargo fmt --check

The TUI core (src/app.rs update) is a pure function with no terminal or network dependency — it is unit-tested directly without a TTY.