After recurring questions on how to run TeamDesk Backup and Restore command-line tools on Mac we decided to give it a chance, but eventually we ended up with a major update… Let’s take a look on what’s new and changed.
Swiss Army Knife
Instead of having two separate programs, one for backup and another for restore now you have one, called td. Whether it will run backup or restore is specified via command argument:
What was:
tdbackup <url> -u <user> -p <password> ...
tdrestore <url> -u <user> -p <password> ...
now is:
td backup <url> -u <user> -p <password> ...
td restore <url> -u <user> -p <password> ...
And we added two more commands, import and export. More on this later.
Cross-platform
The tool now runs on modern versions of Windows, macOS and Linux. Just unpack the archive either with GUI tool or with command in the console:
tar -xvf <archive-name>
and you are ready to go, there is no more extra downloads and installations. On some barebone Linux systems you might need to install additional OS components: (libicu and/or libssl) via OS-specific package manager.
Supported OS versions, for both 64-bit Intel/AMD and ARM64-based processors:
- Windows 10+,
- Windows Server 2012+
- macOS: Catalina+
- Linux: CentOS 7+, Debian 10+, Fedora 36+, openSUSE 15+, Oracle Linux 7+, RHEL 7+, Ubuntu 18.04+
Standard command line
We brought td tools’ command-line interface in par with other widely used command line tools.
- Arguments are now prefixed with double-dash, e.g.
--user
,--file
or--delimiter
. Some commonly used arguments have abbreviations to a single letter, prefixed with single dash:-u
,-f
. - Argument names are case sensitive: -u and –user are valid, -U or –User are not.
- Arguments and their values can be separated with a space, equal sign or colon.
-u test@test.com
or-u:test@test.com
or-u=test@test.com
are all valid. - Use
td --help
(or -? or -h) to list commands ortd command --help
to list command’s arguments and options. - While command line interface is largely compatible with previous version of backup restore tools, please beware there are with few edge-case exceptions.
Response Files
Response files are text files where you can place repeatedly used arguments (either all on a single line or one per line) and pick up the content of the file instead of typing those arguments in the command line. For example, you can create a text file, say apitest.txt with the content:
https://www.teamdesk.net/secure/api/v2/21995
--user test@test.com
--password pwd
and then run
td backup @apitest.txt --verbose
You can use multiple response files per command:
td backup @apitest.txt @csvoptions.txt --verbose
New backup and restore configuration format
There is a still file with configuration settings (td.config.yml), but it is now in YAML format. Long story short, it’s a simple text file with a set of name: value
pairs, one per line. Given we now have all-in-one multi-purpose tool we think the use of config file should be limited to global defaults, while for command specific defaults the use of response files is encouraged.
Import command
In addition to backup and restore commands we added new import and export commands.
Import is a configuration-free, table-specific version of restore. The information restore takes from the configuration file import gets from the command line. For example:
td import <url> -u ... -p ... --file Test.csv --table Test --column Text --column Date=Date --column Created=Timestamp
means “from file Test.csv to table Test import columns file’s Text and Date columns into corresponding columns of the database and Created file’s column into Timestamp database column.” If no columns are specified at all, we try to import all columns from the CSV file into database columns with the same name. If you need to import all but some columns, specify them via –exclude argument.
td import <url> -u ... -p ... --file Test.csv --table Test --exclude Created
This functionality is available in the GUI version of TeamDesk Restore Tool and now it’s usable from the command line as well.
Export command
Export is a freeform data retrieval command
td export <url> -u ... -p ... --file Test.csv --table Test --column Text Date Timestamp --filter "not IsNull([Date])" --sort Date//DESC
By specifying – (minus) as file name you can output the result directly to the console (though in this case files from attachment columns are not downloaded). This allows you to direct the output to some other tools for further processing — this trick is quite common in Unix-based systems but also supported by Microsoft PowerShell.
td export <url> -u ... -p ... --file - --table Test --column Text Date
| ConvertFrom-Csv -d `t | Format-Table
New feature: URL import
In case the data imported to attachment column is URL we now automatically download URL contents and send the file to attachment column.
New option: –culture
By default, numbers and dates are formatted to and parsed out of CSV files using locale and language settings defined by the OS the program runs on. Previously the only option to achieve different output format was to change OS settings. Now you can specify desired locale to format dates and numbers via –culture argument. For example:
td backup ... --culture=en-GB
Backup and Restore GUI tools
So far GUI tools remain Windows-only though we plan to replace them eventually with Web version. Yet, they received new culture (via configuration file) and URL upload feature, deserving new major version.
Feel free to download new version of TeamDesk Backup and Restore Tools.
Wow, thanks Kirill for the continual improvements!