cityair

airtable-cli

a.k.a. "cityair" or "airtable-hacks". Provides a CLI for interacting with NewCity's Airtable tables to perform common tasks (viewing/adding/updating tasks).

Quickstart

1. npm install -g cityair

2. Find your API key by visiting the Account Overview and clicking in the shaded box under the heading "API." This will reveal the API key for you to copy and paste. Save this code for step 4.

3. Find the app key by visiting the API page, clicking the "NC Projects Kanban and Revenue" link at the bottom of the page, and copying the app key out of the URL. It is the second URL fragment that starts with app. Also save this code for step 4.

4. create config ~/.airtable-config.json by adding your name (as it appears in airtable), the API key from step 2, and the app key from step 4. The name you use should be the same as the one you use on your timesheets (not the same as the account name).

   {
     "key": "keyXXXXXXXXXXX",
     "app": "appXXXXXXXXXXX",
     "firstname": "Walter",
     "lastname": "Cronkite"
   }

5. Test the to make sure everything is working and connected by typing airtable-cli cycles. If everything works correctly you should see a list of dates.

6. To get documentation at any time, type airtable-cli --help

airtable-cli <cmd> [args]
 
Commands:
  airtable-cli add [cycle] [task] [hours]   add a new task and estimation
  [actual]
  airtable-cli current                      show current cycle date
  airtable-cli last                         show last cycle date
  airtable-cli next                         show next cycle date
  airtable-cli cycles                       list recent cycles
  airtable-cli tasks [cycle] [sort]         list my tasks
  airtable-cli alloc [cycle]                list my allocation
                                                           [aliases: allocation]
  airtable-cli update [cycle] [hours]       update task status
  airtable-cli edit [cycle]                 update task
  airtable-cli bs [cycle]                   batch status update
                                                         [aliases: batch-status]
  airtable-cli ts [cycle]                   copy in-queue tasks for a project
                                            from Trello   [aliases: trello-sync]
  airtable-cli gi [cycle] [issue]           create a task from a Gitlab issue
                                                         [aliases: gitlab-issue]
  airtable-cli delete [cycle]               delete a task
  airtable-cli wrapup [cycle]               close cards at the end of a cycle
 
Options:
  --version   Show version number                                      [boolean]
  -h, --help  Show help                                                [boolean]
 

Notes:

• You can use current where any cycle is expected to specify the current cycle.
• airtable-cli add and airtable-cli update will both respond with a searchable list of projects; you don't need to specify those on the command line.
• airtable-cli add creates a new task and lets you specify the "Est Hours" column.
• airtable-cli update updates the "Actual Hrs" column.
• airtable-cli edit interactively updates relevant task columns.

Trello integration

Trello card -> task integration needs some additional configuration. Each (Airtable) project must be mapped to a (Trello) board in your ~/.airtable-config.json` file.

Sample configuration:

{
  <snip>
  "trello": {
    "key": "XXXXX",
    "token": "XXXXXXXXXX",
    "username": "ahebrank",
    "projects": [
      {
        "name": "ODU 2018",
        "board_id": "WpLAbg6Z",
        "airtable_project_id": "recRFbgWXpCduGJsM",
        "list": "In Queue"
      }
    ]
  }
}

Trello API keys may be generated at https://trello.com/app-key. Follow the manual token generation link to generate a oauth token. username is your Trello username.

For the project mapping, name is an arbitrary label and has no underlying function. board_id may be found in the URL for a Trello board. airtable_project_id may be found in the airtable-cli allocation output. list must match the name of the in-queue listing on the board.

Running airtable-cli trello-sync will copy any Trello cards assigned to you in the in-queue list to tasks in Airtable. Currently each tasks is estimated at 0 hours when it is copied.