phable

Manage Phabricator tasks from the comfort of your terminal.

phable is a CLI allowing you to manage your Phorge/Phabricator tasks.

It tries to be very simple and not go overboard with features. You can:

• create a new task
• display a task details
• move a task to a column on its current board
• assign a task to a user
• add a comment to a task
• and more (see phable --help output for the full feature list)

Installation

$ pip install phable-cli

Usage

$ phable --help
Usage: phable [OPTIONS] COMMAND [ARGS]...

  Manage Phabricator tasks from the comfort of your terminal

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  assign             Assign one or multiple task ids to a username
  cache              Manage internal cache
  comment            Add a comment to a task
  config             Manage phable config
  create             Create a new task
  list               Lists and filter tasks
  move               Move one or several task on their current project board
  parent             Manage task parents
  report-done-tasks  Print the details of all tasks in the `from` column and move them to the `to` column.
  set                Set the fields of one or multiple tasks
  show               Show task details
  status             Set the status of one or multiple tasks [DEPRECATED]
  subscribe          Subscribe to one or multiple task ids
  tag                Add a tag on one or multiple tasks [DEPRECATED]

A few examples:

$ phable list --status open
$ phable list --status progress --status stalled --milestone

--status can be passed multiple times to match several statuses.

Setup

For phable to work, you need to define the following configuration, by running $EDITOR $(phable config show):

[phabricator]
url = # URL to your phabricator instance. Ex: `url = https://phabricator.wikimedia.org`
token = # API token. Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
default_project_phid = # id for the Phabricator project to be used by default when creating tasks.

To get default_project_phid, define the first 2 configurations, and run the following command, where T123456 is a task id belonging to your project.

$ phable show T123456 --format=json | jq -r '.attachments.projects.projectPHIDs[]'

Note: you can also expose these configuration through the following environment variables, for backwards compatibility:

• PHABRICATOR_URL
• PHABRICATOR_TOKEN
• PHABRICATOR_DEFAULT_PROJECT_PHID

Tips and tricks

Refer to your own phabricator username

You can address your own phabricator username as self. For example, you can assign a task to yourself by running

phable assign --username self T123456

This can be useful when sharing command aliases to another user without having them change the username to their own.

Setting up aliases

You can define command aliases. For example, instead of typing phable move --column 'Done' --milestone T123456, you might want to type phable done T123456. To do this, open the phable configuration file, with $EDITOR $(phable config show) and define an alias:

[aliases]
done = move --column 'Done' --milestone

I personally currently have the following aliases:

$ phable config aliases list
done = move --column 'Done' --milestone
review = move --column 'Needs Review' --milestone
wip = move --column 'In Progress' --milestone
team-report = list --owner self --column 'In Progress' --column 'Needs Review' --column 'Blocked/Waiting' --column Done --milestone --format html

Phabricator task IDs as clickable links in iTerm2

If you're using iTerm2, you can turn the task IDs into clickable links, by going to iTerm2 > Settings > Profiles > Advanced > Smart Selection > Edit > [+]:

• Title: Phabricator Task Id
• Action: Open URL
• Parameter: https://phabricator.wikimedia.org/\0 (Adjust your Phabricator URL)

Then click on the new rule Notes field, and set it to Phabricator, and set the Regular expression field to T\d{6} (adjust the number of digits to what a task ID looks like in your instance. The latest created task has ID 385678 right now, so \d{6} gives us some leeway).

One that is done, holding Command when hovering on a task ID should turn it into a link.

Enabling autocompletion

bash

Add this to ~/.bashrc:

eval "$(_PHABLE_COMPLETE=bash_source phable)"

zsh

Add this to ~/.zshrc:

eval "$(_PHABLE_COMPLETE=zsh_source phable)"

fish

Add this to ~/.config/fish/completions/phable.fish:

_PHABLE_COMPLETE=fish_source phable | source

Contributing

Install all development dependencies using

make init

You can then run every linters and tests that would be run in CI by running:

make ci