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
  edit                Edit the description text of the argument task
  list                Lists and filter tasks
  move                Move one or several task on their current project board
  move-project-tasks  Move tasks from the previous milestone to the new one while keeping their column.
  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
  subscribe           Subscribe to one or multiple task ids

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.

Defining your prefered text editor

Some phable commands, such as create or edit will open a text editor for you to edit the task description.

phable will attempt to respect your choice in term of what editor you would like to use, and perform a sensible guess if no editor is specified.

It will use

1. the content of your EDITOR environment variable
2. what was defined in configuration, under core.editor. For example

[core]
editor = nvim

3. the output of the sensible-editor command (if it can be found)
4. nano (if it is in your PATH)

If none of these options work, an error message will be raised and the command will fail.

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