TorchCL

TorchCL allows you to create messages, time enteries and expenses from the command line. Why might you want to do this? Because if you have terminal access you can build this into an automation routine where otherwise you might need to hire a programmer.

Create a message

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --title "My Title" --body "~/mynewmessage.txt" --files "image.jpg"

What's going on here? The title is explicitly specified as an option, but the body is specified by file; which means the content of "mynewmessage.txt" becomes the content of the message. This is something you can do with any filed in torchCL. Additionally, I've specified a file (in the current directory) I wish to upload.

The body variable will be parsed for task/event, pin, time, expense, category and complete entries as described in this document (and you can have as many of these as you want). Additionly, when using a non-project webhook url, the command [project:name of project] will also be detected.

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --title "My Title" --body "~/mynewmessage.txt" --simulate

The body variable will be parsed for task/event, pin, time, expense, category and complete entries as described in this document (and you can have as many of these as you want). However, the message will not be created.

Create a time entry

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --note "I worked for Pi" --hours "3.14" --category "Time Rat-Hole"

Here we are creating a time entry and placing it in a category.

Create an expense entry

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --note "That Thing!" --price "123.45" --date "10/21/2010" --file "~/receipt.pdf"

So this creates an expense. But in this case I'm saying that I didn't buy it today, but in the past (which I'm specifying with the date option). I'm also specifying a receipt.
TorchCL allows you to list time enteries, expenses, events, invoices, messages, docs and payments.

List time enteries

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "time" --save "results.csv"

So, this will give me a list of all time enteries on this project. In addition to the list term I've instructed torchCL to save the results to a file. If I type something like:

./torchCL --list "time WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design".

List expenses

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "expenses"

This provides a list of all expenses on the current project. You might have noticed in this case I didn't specify a file to save the results to. This means the results will be sent to the terminal window. If I type something like:

./torchCL --list "expenses WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design".

List invoices

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "invoices" --save "results.csv"

This retrieves all of the project invoices and saves them to a file. If I type something like:

./torchCL --list "invoices WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design".

List payments

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "payments" --save "results.csv"

This retrieves all of the project invoices and saves them to a file. If I type something like:

./torchCL --list "payments WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design".

List messages

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "messages"

This provides a list of all expenses on the current project. You might have noticed in this case I didn't specify a file to save the results to. This means the results will be sent to the terminal window. If I type something like:

./torchCL --list "messages WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design". If I type something like:

./torchCL --list "messages WebSite Design" --save "results.csv"

I'll get a plain text file containing each message.

List docs/drive

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "docs"

This provides a list of all expenses on the current project. You might have noticed in this case I didn't specify a file to save the results to. This means the results will be sent to the terminal window. If I type something like:

./torchCL --list "docs WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design". If I type something like:

./torchCL --list "docs WebSite Design" --save "results.csv"

I'll get a plain text file containing each message.

List events

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --list "events" --save "results.csv"

This retrieves all of the uncompleted and pinned events and saves them to a file. If I type something like:

./torchCL --list "events WebSite Design" --save "results.csv"

While using the "all active projects" webhook, I'll get a CSV containing only items in the project "WebSite Design". If I type something like:

./torchCL --list "events" --save "results.txt"

I'll get a plain text file with each event specified as a new line, projects specified with a "+" and categories specified with a "@". This format is commonly used when applying David Allen's Getting Things Done methodology and is compatible with programs like Todo.txt.

Displaying results in the terminal

Instead of saving retrieved results to a file, torchCL allows you to display them in the terminal.

./torchCL --list "events"

This information will be in JSON format, which allows you to pipe it to another command line application. However, you can also view it in plain text by adding the option "--text". For instance:

./torchCL --list "events" --text

The "--text" option can be applied to any extraction command:
  • Listing time (--list="time")
  • Listing expenses (--list="expenses")
  • Listing invoices (--list="invoices")
  • Listing payments (--list="payments")
  • Listing messages (--list="messages")
  • Listing events (--list="events")
  • Listing docs (--list="docs")
Installation

Installing torchCL is pretty easy. Because Macs and Linux already include Python, all you need to do is download the torchCL source, decompress it, and move it wherever you want. Of course, if you use torchCL a lot you might want to add your installation location to your PATH variable.

On Windows, you need to download the torchCL executable. Once you decompress it, you can move the file anywhere you like.

Alternatively, you can install using MacPorts:

sudo port -v selfupdate
sudo port install torchcl

Configuration

TorchCL uses Torch Project Management's webhook (found in Torch's help section). So before you can do anything else you will need to specify where you want to send this data.

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --webhook "https://creativearc.mytorch.net/WEBHOOK"

If you wish to change your webhook in the future, just rerun this command with the new url.

In the terminal where torchCL is installed type (on Windows, or if torchCL is in your path, you would not type the leading "./"):

./torchCL --help

Upgrading

Sense June 2012, TorchCL has been able to detect if it is out-of-date. Just run:

./torchCL --version

If the version is out of date it will attempt to download the new version to your downloads folder (Mac and Linux) or take you to this downloads page (Windows). You can then replace your existing version simply decompressing the download and overwriting your existing copy.