tapioca - Project Management

The Tapioca CLI brings powerful task management and time tracking to your terminal. With the CLI, you can create tasks, log time, manage sprints, and even use a full TUI (Terminal User Interface) for a rich terminal experience.

System Requirements

Operating System: macOS, Linux, or Windows
Architecture: x86_64 or ARM64
Optional: Git (for branch-based task linking)

Installation Methods

Homebrew (macOS/Linux)

The recommended installation method for macOS and Linux users.

# Add the Tapioca tap
brew tap bcp-technology/tapioca

# Install the CLI
brew install tapioca

To upgrade to the latest version:

brew upgrade tapioca

Scoop (Windows)

For Windows users, we recommend Scoop.

# Add the Tapioca bucket
scoop bucket add tapioca https://github.com/bcp-technology/scoop-tapioca

# Install the CLI
scoop install tapioca

Chocolatey (Windows)

Alternative Windows installation via Chocolatey.

choco install tapioca

Direct Download

Download pre-built binaries from our releases page.

Go to Releases

Visit github.com/bcp-technology/tapioca/releases

Download Binary

Choose the appropriate file for your OS and architecture

Extract Archive

Unzip or untar the downloaded file

Move to PATH

Move the binary to a directory in your PATH

Verify

Run 'tapioca --version' to confirm installation

Available downloads:

Platform	Architecture	File
macOS	Intel	`tapioca-darwin-amd64.tar.gz`
macOS	Apple Silicon	`tapioca-darwin-arm64.tar.gz`
Linux	x86_64	`tapioca-linux-amd64.tar.gz`
Linux	ARM64	`tapioca-linux-arm64.tar.gz`
Windows	x86_64	`tapioca-windows-amd64.zip`

Go Install

If you have Go 1.21+ installed:

go install github.com/bcp-technology/tapioca/cmd/tapioca@latest

Make sure $GOPATH/bin (usually ~/go/bin) is in your PATH.

Docker

Run the CLI in a Docker container:

docker run -it --rm 
  -v ~/.tapioca:/root/.tapioca 
  ghcr.io/bcp-technology/tapioca:latest 
  tapioca --help

Shell Alias

Create an alias for easier Docker usage: ```bash alias tapioca='docker run -it --rm -v ~/.tapioca:/root/.tapioca ghcr.io/bcp-technology/tapioca:latest tapioca' ```

Verifying Installation

After installation, verify the CLI is working:

# Check version
tapioca --version

# Output: tapioca version 1.0.0 (abc1234)

# View help
tapioca --help

[Screenshot: Terminal showing tapioca —version output]

Initial Configuration

Authentication

Before using the CLI, you need to authenticate with your Tapioca account.

# Start interactive login
tapioca login

This opens your browser to complete authentication. After logging in, you’ll see:

✓ Successfully logged in as [email protected]
✓ Organization: Acme Corp
✓ Configuration saved to ~/.tapioca/config.yaml

[Screenshot: Browser login flow and terminal success message]

Self-Hosted Users

If you're using a self-hosted Tapioca instance, specify your server URL: ```bash tapioca login --server https://tapioca.yourcompany.com ```

Configuration File

The CLI stores configuration in ~/.tapioca/config.yaml:

# Server connection
server: https://api.tapioca.app
# or for self-hosted: server: https://tapioca.yourcompany.com

# Authentication
auth:
  token: "your-access-token"
  refresh_token: "your-refresh-token"
  expires_at: "2024-12-31T23:59:59Z"

# Default organization
organization: "org_abc123"

# Default project (optional)
project: "proj_xyz789"

# Output preferences
output:
  format: "table"  # table, json, yaml
  color: true
  pager: true

# TUI preferences
tui:
  theme: "default"
  refresh_interval: 30

Environment Variables

You can also configure the CLI via environment variables:

Variable	Description	Example
`TAPIOCA_SERVER`	Server URL	`https://api.tapioca.app`
`TAPIOCA_TOKEN`	API token (bypasses login)	`tap_xxxxx`
`TAPIOCA_ORG`	Default organization ID	`org_abc123`
`TAPIOCA_PROJECT`	Default project ID	`proj_xyz789`
`TAPIOCA_OUTPUT`	Output format	`json`
`NO_COLOR`	Disable colored output	`1`

CI/CD Usage

For CI/CD pipelines, use `TAPIOCA_TOKEN` with an API token instead of interactive login: ```bash export TAPIOCA_TOKEN="tap_your_api_token" tapioca task list --project myproject ```

Switching Organizations

If you belong to multiple organizations:

# List your organizations
tapioca org list

# Switch to a different organization
tapioca org switch "Other Company"

# Or by ID
tapioca org switch org_def456

Shell Completion

Enable tab completion for your shell.

Bash

# Add to ~/.bashrc
source <(tapioca completion bash)

# Or generate file
tapioca completion bash > /etc/bash_completion.d/tapioca

Zsh

# Add to ~/.zshrc
source <(tapioca completion zsh)

# Or add to fpath
tapioca completion zsh > "${fpath[1]}/_tapioca"

Fish

tapioca completion fish > ~/.config/fish/completions/tapioca.fish

PowerShell

# Add to your PowerShell profile
tapioca completion powershell | Out-String | Invoke-Expression

After adding completion, restart your shell or source the configuration file.

[Screenshot: Terminal showing tab completion in action]

IDE Plugins

Enhance your development workflow with IDE plugins that automatically track time while you code.

VS Code Extension

Open Extensions

Press Cmd/Ctrl+Shift+X or click the Extensions icon

Search

Search for 'Tapioca'

Install

Click Install on 'Tapioca for VS Code'

Authenticate

Click the Tapioca icon in the sidebar and sign in

Configure

Set your default project in extension settings

[Screenshot: VS Code with Tapioca extension installed]

Features:

Automatic time tracking while coding
Branch-based task detection
Status bar showing current task and timer
Quick task switching via command palette
View tasks in sidebar

Extension Settings:

Setting	Description	Default
`tapioca.server`	Server URL	`https://api.tapioca.app`
`tapioca.autoTrack`	Enable automatic tracking	`true`
`tapioca.idleTimeout`	Minutes before pausing	`5`
`tapioca.branchPattern`	Regex to extract task ID from branch	`(TASK-\d+)`

JetBrains IDEs

Works with IntelliJ IDEA, WebStorm, PyCharm, GoLand, and other JetBrains IDEs.

Open Plugins

Go to Settings → Plugins → Marketplace

Search

Search for 'Tapioca'

Install

Click Install and restart the IDE

Authenticate

Go to Settings → Tools → Tapioca and sign in

Configure

Set your server URL and preferences

[Screenshot: JetBrains IDE with Tapioca plugin]

Features:

Automatic time tracking
Tool window showing current tasks
Git branch integration
Status bar widget
Quick actions via IDE actions

Branch-Based Task Linking

IDE plugins can automatically link time to tasks based on your Git branch name.

How It Works

You create a branch with a task ID in the name
The plugin detects the branch name
Time is automatically tracked to that task

Supported Branch Patterns

The default pattern recognizes:

feature/TASK-123-add-login
bugfix/TASK-456
TASK-789-refactor

Configure custom patterns in plugin settings:

# Default pattern
(TASK-d+)

# Multiple prefixes
(TASK|BUG|FEAT)-d+

# Project prefix
(PROJ-d+)

Branch Naming Convention

Adopt a consistent branch naming convention like `type/TASK-123-description` for reliable automatic linking.

Manual Task Selection

If automatic detection doesn’t work or you need to override:

VS Code:

Click the Tapioca icon in the status bar
Select “Change Task”
Search and select the task

JetBrains:

Click the Tapioca widget in the status bar
Select a different task from the dropdown

Updating the CLI

Homebrew

brew upgrade tapioca

Scoop

scoop update tapioca

Go Install

go install github.com/bcp-technology/tapioca/cmd/tapioca@latest

Checking for Updates

# Check if updates are available
tapioca version --check

# Output:
# Current version: 1.0.0
# Latest version: 1.1.0
# Update available! Run 'brew upgrade tapioca' to update.

Uninstalling

Homebrew

brew uninstall tapioca

Scoop

scoop uninstall tapioca

Manual

Remove the binary from your PATH
Delete the configuration directory:
```
rm -rf ~/.tapioca
```

Troubleshooting

“Command not found”

If tapioca is not recognized:

Check PATH: Ensure the installation directory is in your PATH
```
echo $PATH
```
Restart terminal: Close and reopen your terminal

Verify binary location:

which tapioca
# or on Windows
where tapioca

Authentication Errors

If login fails:

Check internet connection: Ensure you can reach the server
Clear credentials: Remove stored tokens
```
rm ~/.tapioca/config.yaml
tapioca login
```
Check server URL: Verify you’re using the correct server

IDE Plugin Not Connecting

Check authentication: Ensure you’re logged in via the plugin
Verify server URL: Check plugin settings match your CLI config
Check firewall: Allow connections to the Tapioca server
View logs: Check IDE log files for error messages

Slow Performance

Check network latency: Try pinging the server
Use caching: Enable offline mode for faster reads
```
tapioca config set cache.enabled true
```

Getting Help

If you continue to have issues: - Run `tapioca doctor` for diagnostic information - Check GitHub issues at github.com/bcp-technology/tapioca/issues - Contact support with the output of `tapioca debug-info`

Next Steps

CLI Commands - Complete command reference
Time Tracking - Track time from the CLI
Tasks - Manage tasks with the CLI

System Requirements

Installation Methods

Homebrew (macOS/Linux)

Scoop (Windows)

Chocolatey (Windows)

Direct Download

Go to Releases

Download Binary

Extract Archive

Move to PATH

Verify

Go Install

Docker

Verifying Installation

Initial Configuration

Authentication

Configuration File

Environment Variables

Switching Organizations

Shell Completion

Bash

Zsh

Fish

PowerShell

IDE Plugins

VS Code Extension

Open Extensions

Search

Install

Authenticate

Configure

JetBrains IDEs

Open Plugins

Search

Install

Authenticate

Configure

Branch-Based Task Linking

How It Works

Supported Branch Patterns

Manual Task Selection

Updating the CLI

Homebrew

Scoop

Go Install

Checking for Updates

Uninstalling

Homebrew

Scoop

Manual

Troubleshooting

“Command not found”

Authentication Errors

IDE Plugin Not Connecting

Slow Performance

Next Steps

Was this page helpful?