{
  "markdown": "# active-collab-cli\n\n**Unofficial** command-line tool and interactive terminal UI (TUI) for reading\nand browsing [ActiveCollab](https://activecollab.com) tasks from self-hosted\ninstances. Supports multi-instance configuration, SQLite-backed token storage,\nand outputs human-readable or JSON task views.\n\nThe application ships as a single self-contained binary (`ac`) built with Rust\n(ratatui + crossterm + tokio). No interpreter or runtime is required on the target.\n\n> ## ⚠️ Unofficial — not affiliated with ActiveCollab\n>\n> This is an independent, community-built project. It is **not** an official\n> ActiveCollab product and is **not affiliated with, endorsed by, sponsored by,\n> or supported by** ActiveCollab or A51 d.o.o. **\"ActiveCollab\" is a trademark of\n> its respective owner** and is used here **only** to describe compatibility with\n> the ActiveCollab REST API of your own self-hosted instance. This tool stores no\n> credentials beyond a local API token, sends that token only to your configured\n> host, and is provided \"as is\", without warranty. Use at your own risk.\n\n---\n\n## Screenshot\n\n![The ac browse task-detail view, rendered with fictional demo data](docs/assets/detail-demo.svg)\n\n*Interactive TUI — the task-detail view (project, status, description, assets).\nThe data shown is fictional; no real instance or client data is depicted.*\n\n---\n\n## Quickstart\n\nFrom zero to your first task in three steps:\n\n```sh\n# 1 · Install (macOS / Linux — Windows: see the PowerShell one-liner below)\ncurl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.sh | sh\n\n# 2 · Register your self-hosted ActiveCollab instance.\n#     Prompts once for your password to exchange an API token — the password is never stored.\nac setup add --name collab --url https://collab.example.com --email you@example.com\n\n# 3 · List the open tasks assigned to you\nac mine\n```\n\nThen, day to day:\n\n```sh\nac                  # the task for your current git branch (e.g. feature/665-75159)\nac get 665/75159    # a specific task by short form or full URL\nac browse           # full interactive TUI: projects → tasks → detail → assets\nac mine --json      # machine-readable output for scripts and agents\n```\n\nNew here? `ac setup add` walks you through it interactively if you omit the flags.\nSee [Usage](#usage) for every command and flag.\n\n---\n\n## Install\n\n### macOS / Linux (curl one-liner)\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.sh | sh\n```\n\nThe script downloads the pre-built `active-collab` binary for your platform from\nthe latest GitHub Release and places it on your PATH, next to an `ac` symlink —\nthe short command used throughout this README and by the agent skill. An `ac`\nleft by an older install is replaced; an `ac` belonging to another program is\nkept, with a warning. macOS ships its own `/usr/sbin/ac` (login accounting), so\nthe installer also warns when that one still wins your PATH lookup.\n\n### Windows (PowerShell one-liner)\n\n```powershell\nirm https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install.ps1 | iex\n```\n\nInstalls `active-collab.exe` plus an `ac.cmd` shim, so both `active-collab` and\n`ac` work from cmd and PowerShell.\n\n### Manual download\n\nDownload the pre-built binary for your platform from the\n[Releases page](https://github.com/ejklock/active-collab-cli/releases), place it on your\nPATH, and make it executable (`chmod +x active-collab` on Unix). Add the short\nalias yourself: `ln -s active-collab ac` (Unix), or an `ac.cmd` forwarder on\nWindows.\n\n| Platform | Asset |\n|---|---|\n| Linux x86\\_64 | `active-collab-linux-x86_64` |\n| macOS x86\\_64 (Intel) | `active-collab-macos-x86_64` |\n| macOS arm64 (Apple Silicon) | `active-collab-macos-arm64` |\n| Windows x86\\_64 | `active-collab-windows-x86_64.exe` |\n\n### Build from source (Docker required)\n\nNo local Rust toolchain needed. The crate is at the repo root; Docker provides\nthe build environment.\n\n```sh\n# Development build\ndocker compose run --rm dev cargo build\n\n# Release binary (placed in target/release/ac)\ndocker compose build\ndocker compose run --rm build\n```\n\nThat binary is a Linux build. `make install` therefore only accepts a Linux host\nand refuses elsewhere; on macOS use `make install-native` (needs a host Rust\ntoolchain) or the release installer above.\n\n---\n\n## Usage\n\n### Setup — manage instances\n\n```sh\n# Register an ActiveCollab instance (interactive wizard prompts for missing fields)\nac setup add\nac setup add --name collab --url https://collab.example.com --email me@example.com\n# Password is always entered hidden via a prompt — never passed as a flag.\n\n# List configured instances (tokens never shown)\nac setup list\n\n# Remove an instance and its cached tasks\nac setup remove --name collab\n\n# Test connectivity to all (or one) configured instance\nac setup test\nac setup test --name collab\n\n# Show the current display language\nac setup language\n\n# Set the display language (persists to SQLite; survives across invocations)\nac setup language en\nac setup language pt_BR\n```\n\n### get — fetch a task by URL or short form\n\n```sh\nac get 665/75159\nac get https://collab.example.com/projects/665/tasks/75159\n```\n\n### current — fetch the task from the current git branch\n\nBranch must match `(feature|hotfix|fix)/PROJECT_ID-TASK_ID` (e.g. `feature/665-75159`).\n\n```sh\nac current\n```\n\n### mine — list open tasks assigned to you\n\n```sh\nac mine\nac list          # alias\n```\n\nWhen run in a terminal (TTY), `mine` opens an interactive arrow-key list of your\nopen tasks aggregated across all configured instances. Select a task to view its\ndetail or open/download its assets. When output is piped or redirected (non-TTY),\n`mine` falls back to a plain table suitable for scripts.\n\n### browse — interactive TUI\n\nArrow-key terminal browser for your open tasks. Navigate projects → tasks →\ntask detail, then open/download the task's assets.\n\n```sh\nac browse\nac browse --instance collab   # required when >1 instance configured\n```\n\nThe TUI uses ratatui for layout and crossterm for input, giving consistent mouse\nclick, scroll, and keyboard behavior on Linux, macOS, and Windows. It shows a\nloading indicator during fetches and guards against duplicate in-flight refresh\nrequests (single-flight).\n\nThe task detail view shows:\n\n- **Meta table** — a two-column table listing Task, Project, Title, Status,\n  Assignee, Start, Due, Estimate, and Logged.\n- **Description** — the task body; falls back to `(no description)` when empty.\n- **Artifacts panel** — lists each image / attachment / link as `[n] name` with\n  its URL. Press `1`–`9` to open the matching artifact in your browser.\n- **Comments** — one panel per comment (author · date as the panel title).\n\nThe detail view scrolls vertically when content exceeds the screen. The TUI\nadapts to terminal resize events and guards against too-small terminals without\ncrashing. The footer shows key-cap style hints (`[key] action`).\n\nEach task you open is written to the local SQLite `ticket_cache` keyed by instance\nname; re-opening the same task is instant and offline-tolerant. Press `r` inside\nthe detail view to bypass the cache and re-fetch from the API.\n\n**Key bindings**\n\n| Screen | Keys |\n|---|---|\n| Projects / Tasks lists | `↑`/`↓` or `k`/`j` move · `Enter` select · `q` quit · `b` back · `s` settings |\n| Task detail | `↑`/`↓` or `k`/`j` scroll · `PgUp`/`PgDn` page · `a` assets · `r` refresh · `1`–`9` open artifact · `q`/`b` back |\n| Settings | `↑`/`↓` or `k`/`j` move · `Enter` select · `q`/`b` back |\n| Assets | `↑`/`↓` or `k`/`j` move · `o` open in browser · `d` download · `q`/`b` back |\n\n**Settings screen** — press `[s]` from any list screen to open the Settings panel.\nIt offers two pickers:\n\n- **Language** — choose `en` (English) or `pt_BR` (Portuguese (Brazil)). The\n  selection persists to SQLite and takes effect immediately without restarting.\n- **Active instance** — choose which configured instance `browse` uses by default\n  when you have more than one. The selection persists to SQLite.\n\n- **Assets** — image, attachment, and link URLs extracted from the task body,\n  comments, and attachments. `o` opens the URL in your browser; `d` downloads\n  it. The `X-Angie-AuthApiToken` header is attached **only** when the asset\n  URL's scheme and host match the configured instance — foreign hosts are\n  fetched without credentials.\n\n### Bare-invocation shortcuts\n\n```sh\nac 665/75159     # same as: ac get 665/75159\nac               # same as: ac current (when branch matches)\n```\n\n### Flags\n\n| Flag | Applies to | Effect |\n|---|---|---|\n| `--instance NAME` | `get`, `current`, `mine`, `browse` | Force a specific configured instance (required when >1 configured) |\n| `--short` | `get`, `current` | Print `PROJECT/TASK<TAB>name` only |\n| `--no-comments` | `get`, `current` | Omit the comments section |\n| `--json` | `get`, `current` | Print raw task JSON (always hits the API, bypasses cache) |\n| `--refresh` | `get`, `current` | Bypass the task cache and re-fetch from the API |\n\n---\n\n## Agent skill\n\n`ac` ships a self-describing **agent skill** for the `--json` read contract, so an\nLLM coding agent can learn how to read your ActiveCollab tasks non-interactively.\nThe full contract lives in **one place** — inside the binary — and `ac` prints it on\ndemand:\n\n```sh\nac skill list           # list the available skills\nac skill active-collab  # print the full active-collab contract (schemas, the round-trippable ref, flags)\nac skill                # with one skill registered, prints it directly\n```\n\n### Install the skill into your agent harness\n\nEvery supported harness loads a small **thin pointer** whose only job is to tell the\nagent to run `ac skill active-collab`. Because the pointer carries no schema, it never goes\nstale when the `--json` contract changes — only the binary does. Run the installer\nfrom your project root for the harness you use (or `all`):\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness cursor\n# or wire up every harness at once:\ncurl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness all\n```\n\n| Harness | Project file (`--scope project`, default) | User-level file (`--scope global`) |\n|---|---|---|\n| Claude Code | `.claude/skills/active-collab/SKILL.md` | `~/.claude/skills/active-collab/SKILL.md` |\n| pi | `.pi/skills/active-collab/SKILL.md` | `~/.pi/agent/skills/active-collab/SKILL.md` |\n| Codex CLI | `.codex/skills/active-collab/SKILL.md` | `~/.codex/skills/active-collab/SKILL.md` |\n| OpenCode | `.opencode/skills/active-collab/SKILL.md` | — (install per-project) |\n| GitHub Copilot | `.github/skills/active-collab/SKILL.md` | — (install per-project) |\n| Cursor | `.cursor/rules/active-collab.mdc` | — (install per-project) |\n\nClaude Code, OpenCode, and pi can also read `.claude/skills/active-collab/SKILL.md`\ndirectly.\n\n**Scope.** By default the installer writes into the **current project**\n(`--scope project`); pass `--dir <path>` to target another project. Use\n`--scope global` to install once at the **user level** so the skill is available in\nevery project:\n\n```sh\n# install the active-collab pointer once, for every harness that supports a user-level dir\ncurl -fsSL https://raw.githubusercontent.com/ejklock/active-collab-cli/main/install-skill.sh | sh -s -- --harness all --scope global\n```\n\nGlobal scope supports Claude Code, pi, and Codex (the harnesses with a standard\nuser-level skills directory). OpenCode, Copilot, and Cursor have no such directory, so\n`--scope global` reports them as unsupported — install those per-project. Running the\ninstaller directly in a terminal (not via `curl | sh`) prompts for project-vs-global; the\npiped one-liner stays non-interactive and defaults to project. To install into a specific\npi profile, use `--scope project --dir ~/.pi/agent-profiles/<name>`.\n\n> This tool only ever **reads** your ActiveCollab tasks over the `--json` contract; the\n> skill grants an agent no write access beyond the CLI commands you already run yourself.\n\n---\n\n## Internationalization\n\nThe binary ships with English (default) and Brazilian Portuguese (`pt_BR`)\ntranslations for all user-facing output. Translations are embedded at compile time\nas JSON catalogs — no external files required at runtime.\n\n**Durable setting** — persist your preferred language to SQLite:\n\n```sh\nac setup language pt_BR   # set\nac setup language          # show current\n```\n\n**One-off override** — the `ACTIVE_COLLAB_LANG` environment variable overrides the\nstored setting for a single invocation:\n\n```sh\nACTIVE_COLLAB_LANG=pt_BR ac browse\n```\n\n**Resolution order:** `ACTIVE_COLLAB_LANG` env var → SQLite setting → `en`.\n\nThe language can also be changed interactively from inside `browse` — press `[s]`\nto open Settings and select a language; the change takes effect immediately without\nrestarting.\n\n---\n\n## Configuration\n\n**Database path:** `~/.config/active-collab/active-collab.db`\n\nOverride with the `ACTIVE_COLLAB_DB` environment variable:\n\n```sh\nACTIVE_COLLAB_DB=/custom/path/active-collab.db ac get 665/75159\n```\n\n---\n\n## Security\n\n- The API token is stored only in the local SQLite database with directory\n  permissions `0700` and file permissions `0600`.\n- The token is transmitted exclusively via the `X-Angie-AuthApiToken` HTTP header —\n  never in a URL, never printed, never passed as a process argument.\n- The password is **never stored**. Only the token returned from the issue-token\n  endpoint is persisted.\n- The token is sent only to the configured instance's own host. Requests to asset\n  URLs on other hosts carry no token.\n\n---\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | Task not found / HTTP error / parse error |\n| 2 | Usage error, unknown instance, no instances configured, branch mismatch |\n\n---\n\n## Development\n\n```sh\n# Run all tests (unit + integration, including comment-policy gate)\ndocker compose run --rm dev cargo test\n\n# Run only the comment-policy gate\ndocker compose run --rm dev cargo test --test comment_policy\n\n# Lint\ndocker compose run --rm dev cargo clippy -- -D warnings\n\n# Format check\ndocker compose run --rm dev cargo fmt --check\n```\n\nThe TUI core (`src/app.rs` `update`) is a pure function with no terminal or\nnetwork dependency — it is unit-tested directly without a TTY.\n",
  "bytes": 14349,
  "sha": "f0812aa5a539d15b6ea63953b62574e5221de943ecc8cdf80a2ad7d1d9477dcf",
  "repo_slug": "ejklock/active-collab-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_ejklock_active_collab_cli_docs_index_md_95ba98d3/readme"
}