🚀 tq is a command-line interface for Tessitura

tq is a wrapper around the Tessitura API that reads JSON-formatted data and executes a series of API calls to Tessitura. It internally handles authentication and batch/concurrent processing so that humans like you (or bots or scripts) can focus on the data and not the intricacies of the Tessitura API.

🏗️ installation

from binary

Download the latest release from the releases page!

from source

The only prerequisite to building tq is installing go.

Then clone this repository and build:

git clone github.com/skysyzygy/tq
cd tq
go build -o bin/tq .

The build command will create an executable file tq or tq.exe in the bin project directory.

🪪 authentication

To authenticate with the API server you need to add one or more authentication methods. The authentication secret will be saved in one of these supported managers: - macOS - Keychain - Windows - Credential Manager - Unix - Pass - Azure - Key Vault: enabled as the key manager whenever the environment variable AZURE_KEY_VAULT is present and set to the fully qualified name of the key vault (e.g. https://myvault.vault.azure.net)

tq auth add --host hostname --user username --group usergroup --location location
# Password: ******

The default authentication can then be selected by: * using the command line shell tq auth sel --host hostname --user username --group usergroup --location location * adding a line to the ~/.tq config file (which is just what the above command does!): shell login: hostname|username|usergroup|location * using an environment variable: export TQ_LOGIN="hostname|username|usergroup|location" tq get constituents <<< '{"constituentid":"1"}' * using an environment variable and Azure Key Vault: export AZURE_KEY_VAULT=my-key-vault export TQ_LOGIN="hostname|username|usergroup|location" tq get constituents <<< '{"constituentid":"1"}'

🍳 recipes

get constituent info

tq get constituents <<< '{"constituentid": "12345"}'

update a constituent address

tq update addresses <<< '{"addressid": "12345", "street1": "123 New Street"}'

add a plan step

tq create steps <<< '{"plan": {"Id": 12345}, "type": {"Id": 1}, "Description": "New step!", "Notes": "Created by tq :)"}'
# or using flattened syntax
tq --inflat create steps <<< '{"plan.Id": 12345, "type.Id": 1, "Description": "New step!", "Notes": "Created by tq :)"}'

🛠️ usage

tq [flags] [verb] [object]

flags:

  • -c, --compact compact instead of indented output
  • -n, --dryrun don't actually do anything, just show what would have happened
  • -f, --file input file to read (default is to read from stdin)
  • --headers additional headers to include in outgoing requests in name=value,name=value format (or in JSON format when used in the TQ_HEADERS environment variable)
  • --highlight render json with syntax highlighting; default is to use highlighting when output is to terminal
  • -i, --in input format (csv or json; default is json); csv implies --inflat
  • --inflat use input flattened by JSONPath dot notation. Combining this with --help will show the flattened format
  • -l, --log log file to write to (default is no log)
  • --no-highlight render json without syntax highlighting; default is to use highlighting when output is to terminal
  • -o, --out output format (csv or json; default is json); csv implies --outflat
  • --outflat use output flattened by JSONPath dot notation
  • -v, --verbose turns on additional diagnostic output

configuration file:

A yaml configuration file .tq placed in your home directory can be used to set defaults for these flags; it is also used to save the current authentication method. See tq auth select --help for more information.

environment variables:

All flag options can also be set as environment variables, in all caps, with a TQ_ prefix, for example, TQ_OUT=csv will set the output format to csv.

verbs:

  • authenticate : Authenticate with the Tessitura API
  • create : Create entities in Tessitura
  • get : Retrieve entities from Tessitura
  • update : Update entities in Tessitura
  • completion : Generate the autocompletion script for the specified shell
  • help : Help about any command

❓ queries

Queries are simply JSON objects and can be batched by combining multiple query objects into a single JSON array, e.g. 

[{"ID":123}, {"ID":124}, {"ID":125}, {}, {}, ]

Query object details are detailed in the help for each command.

Queries can be sent to tq by:

  1. writing them to a file, e.g. a file like this:

query.json

{"CustomerId":"12345"}

tq -f query.json get constituents
# ...or
tq get constituents < query.json
  1. By piping them on the command line to tq directly:
echo {"CustomerId":"12345"} | tq get constituents
  1. By using a here-string:
# bash
tq get constituents <<< '{"CustomerId":"12345"}'

# powershell
'{\"CustomerId\":\"12345\"}' | tq get constituents
  1. Or for longer queries, using a here-doc!
# bash
tq get constituents <<EOF 
[
      {"CustomerId":"12345"},
      {"CustomerId":"12346"},
      {"CustomerId":"12347"},
      {"CustomerId":"12348"}
]
EOF

# powershell
@'
[
      {"CustomerId":"12345"},
      {"CustomerId":"12346"},
      {"CustomerId":"12347"},
      {"CustomerId":"12348"}
]
'@ | tq get constituents