Webtask

Documentation

wt

Command line interface for webtasks

For customized documentation and ready to run samples, please log in.

Setup

wt is a Command Line Interface (CLI) for using webtasks. This document will provide an overview of the commands you can use to create and manage your microservices. If you haven't installed wt already, go ahead.

Install the CLI

Commands

wt offers a variety of operations so you can easily manage your webtasks. To use these open a terminal and type wt followed by a space and the subcommand you want to use: wt {subcommand}.

  • init: create and update webtask profiles
  • create: create and update webtasks
  • ls: list named webtasks
  • rm: remove a named webtask
  • serve: run a webtask as a local http server
  • edit: edit a webtask in your browser
  • inspect: inspect named webtasks and webtasks tokens
  • update: update the code of a named webtask
  • profile: manage webtask profiles
  • cron: manage scheduled webtasks
  • logs: view streaming, real-time logs
  • token: use advanced operations on webtask tokens
  • bundle: work with bundled webtasks

init

This is the very first command you will run once you install wt. It is used to create and update webtask profiles. It also provisions a webtask token if you don't have one already. Each webtask profile has a name, a URL and a container. In order to configure a webtask profile you need to provide an email or phone number. You will receive a verification code there which you will have to input to the terminal. For more details you can use the wt built-in help.

$ wt init -h 

create

Use this to create and update webtasks. It receives as input a path or URL of the webtasks's code and provides as output the URL where the webtask is available. There are several optional modifiers that can be utilized when creating webtasks. Some examples are:

  • Use --secret KEY=VALUE to attach sensitive information as a "secret". This information will be encrypted and can only be decrypted by the webtask server.
  • Use --secrets-file FILENAME to attach sensitive information as "secrets" from a file. Lines in this file should be structured as KEY=VALUE pairs. This information will be encrypted and can only be decrypted by the webtask server.
  • Use --watch to watch for file changes and refresh the webtask.
  • Use --prod to allow the webtask server to cache the webtask's code between runs.
  • Use --host to set a custom domain name for the webtask.
For more details on the command, its modifiers and how to use them, you can use the wt built-in help.
$ wt create -h

ls

Use this to list your named webtasks. The output will be the Name and URL of each named webtask, listed alphabetically. You can use the pagination modifiers if you need to limit the number of webtasks returned:

  • Use--offset followed by a number to skip this many webtasks starting from the first. This example skips the first two webtasks of the list:
    $ wt ls --offset 2
  • Use--limit followed by a number to retrieve this many webtasks starting from the first. This example lists the first two webtasks of the list:
    $ wt ls --limit 2
There are several other modifiers that can be utilized to set the output format, show more details, display the webtask tokens, and more. For more details use the wt built-in help.
$ wt ls -h

rm

Use this to delete named webtasks. It receives as input the name of the webtask to delete. For more details you can use the wt built-in help.

$ wt rm -h

serve

Use this to run a webtask as a local http server. It receives as input the path to the webtask's source code. Optionally you can specify the port on which the webtask server will listen (argument port) and the hostname for the http listener (argument hostname). To run a webtask based on file hello.js, under localhost:1234 use the following:

$ wt serve hello.js --hostname localhost --port 1234
For more details on setting secrets, storage and other parameters, you can use the wt built-in help.
$ wt serve -h

edit

Use this to load a webtask in your browser. From there you can edit and run it. To edit a webtask named "foo" run the following command in your terminal:

$ wt edit foo
Opening foo in your browser...

wt-edit-webtask

Also you will be able to create a new webtask with Webtask Editor by running the following command in your terminal:

$ wt edit
Opening foo in your browser...

wt-edit-webtask

In addition to editing the code of the webtask, Webtask Editor allows you to modify associated secrets and metadata, integrate your webtask with GitHub and view realtime logs.

inspect

Use this to inspect the claims of a token. As input you have to specify either the subject token or the webtask name, both have the same result. You can ask for the decrypted secrets using --decrypt or the webtask code using --fetch-code. The output displays token claims like the JWT unique identifier (JWT ID - jti), the time at which the JWT was issued (Issued At - iat), the URL of the webtask code to execute (url), and more. For more details you can use the wt built-in help.

$ wt inspect -h

update

Use this to update the code of a named webtask. It has one required input argument and that is the name of the webtask to update. Optionally you can also specify a path or URL of the webtask's code. When not specified, code will be read from standard input. So, if you had a webtask named foo and you wanted to update its code to display "Goodbye" instead of "Hello" the command could be the following.

$ echo "module.exports = function(cb) { cb(null, 'Goodbye'); }" | wt update foo
If you wanted to update the webtask with the contents of the file foo.js, then the command would be the following.
$ wt update foo foo.js
You can set the output format using--output, display the tokens using --show-token, bundle code into a single webtask using --bundle, and more. To review all the different options and their syntax you can use the wt built-in help.
$ wt update -h

profile

Use this to manage your webtask profiles. It can take a set of subcommands as input using the format wt profile {subcommand}. You can use init to create and update webtask profiles, ls to list them all, get to get information about a specific profile, rm to delete a specific profile, and nuke to delete them all. You can also use additional options like --details to display additional details on token claims, or --show-token to display the, hidden by default, tokens. To review all the different options and their syntax you can use the wt built-in help, either at profile or subcommand level.

$ wt profile -h
$ wt profile init -h

cron

Use this to manage your scheduled tasks. The schedule can be either a cron-formatted schedule or an interval of hours ("h") or minutes ("m"). To create a webtask that runs every five minutes use wt cron schedule 5m ./sample-webtasks/hello-world.js. To create a webtask that runs every Tuesday at 09:05 use wt cron schedule "5 9 * * 2" ./sample-webtasks/hello-world.js. Note that not all intervals are supported; only those that can be represented as CRON specs. For example, every 5 hours does not evenly divide a day and so can't be used. Besides scheduling webtasks, you can list all cron jobs using ls, get information on a specific one using get, delete a cron job using rm, and review the history of a specific cron job using history. To review all the different options and their syntax you can use the wt built-in help, either at cron or subcommand level.

$ wt cron -h
$ wt cron get -h

logs

Use wt logs to connect to streaming logs and view them real-time. Escape using Ctrl+C. You can view the logs in raw format using --raw , show verbose logs using --verbose , and more. Note that these commands are for advanced use only in most scenarios. For more details you can use the wt built-in help.

$ wt logs -h

token

Use this to create, inspect, or revoke a token. To review all the different options and their syntax you can use the wt built-in help, either at token or subcommand level.

$ wt token -h
$ wt token create -h

bundle

Use this to work with the webtask bundler. You can compare the module dependencies of your webtask with modules on the Webtask platform using analyze, or update the version of each module in your package.json with the closest version available on webtask.io. For more details you can use the wt built-in help.

$ wt bundle -h

Bundling

Webtasks bundling provides you with the ability to organize your webtask code and work with any modules available on npm. You only need to bundle the modules that are not natively available on the webtask platform. Use webtask-bundle to bundle your code into a single file. This tool can compile ES2015 (ES6) code via Babel as well as packaging up a webtask composed of multiple files into a single file. The tool will scan your package.json for dependencies and will automatically bundle those that are not available on the webtask platform.

For details on how to setup and use the tool visit github.com/auth0/webtask-bundle .

Metadata support

Metadata is an arbitrary set of string key / value pairs that are used to describe a webtask, token or CRON job. Now you can specify metadata using the wt cli. You can set metadata for the following operations:

  • wt create --meta KEY=VALUE: Add metadata to describe a webtask.
  • wt ls --meta KEY=VALUE: Use metadata to filter the webtasks to be listed. Only webtasks with matching metadata will be returned.
  • wt cron schedule --meta KEY=VALUE: Add metadata to describe a scheduled webtask.
  • wt cron ls --meta KEY=VALUE: Use metadata to filter the CRON jobs to be listed. Only scheduled webtasks with matching metadata will be returned.

More

Explore more at github.com/auth0/wt-cli