Command Line Reference

You can use the Command Line Interface (CLI or CDAP CLI) to interact with the CDAP server from within a shell, similar to the HBase or bash shells. It is included by default within the CDAP Sandbox.

It can be installed on Distributed CDAP, in which case it will be installed in /opt/cdap/cli.

You can use the CLI in two modes:

  • Interactive mode

  • Non-interactive mode

Interactive Mode

To run the CLI in interactive mode, run the cdap cli executable with no arguments from a terminal:

  • Linux: $./bin/cdap cli

  • Windows: > .\bin\cdap.bat cli

  • Distributed CDAP: $ /opt/cdap/cli/bin/cdap cli

The executable should bring you into a shell, with a prompt similar to:

1 cdap (http://localhost:11015/namespace:default)>

This indicates that the CLI is currently set to interact with the CDAP server at localhost.

  • To interact with a remote CDAP server, run the CLI by specifying the uri --link example.com.

  • To change the current CDAP server, run the CLI command connect-link example.com.

  • To connect to an SSL-enabled CDAP server, run the CLI with arguments --link https://example.com.

For example, with the arguments --link example.com, the CLI interacts with a CDAP instance at example.com, using the port 11015:

1 cdap (http://example.com:11015/namespace:default)>

To list all of the available commands, enter the CLI command help:

1 cdap (http://localhost:11015/namespace:default)> help

In this documentation, to save space, this prompt is abbreviated to:

1 cdap >

Non-Interactive Mode

To run the CLI in non-interactive mode, run the CDAP CLI executable, passing the command you want executed as the argument. For example, to list all applications currently deployed to CDAP, execute:

  • Linux: $ cdap cli list apps

  • Windows: > cdap.bat cli list apps

Connecting to Secure CDAP Instances

When connecting to secure CDAP instances, the CLI will look for an access token located at ~/.cdap.accesstoken.<hostname> and use it if it exists and is valid. If not, the CLI will prompt you for the required credentials to acquire an access token from the CDAP instance. Once acquired, the CLI will save it to ~/.cdap.accesstoken.<hostname> for later use and use it for the rest of the current CLI session.

Usage example

cdap cli [--autoconnect <true|false>] [--debug] [--help]

         [--verify-ssl <true|false>] [--uri <uri>] [--link <uri>]

         [--namespace <namespace>] [--script <script-file>] [-r |-retries N]

Options

The CDAP CLI uses the following options:

Option

Argument

Description

Option

Argument

Description

--autoconnect
--a

true|false

If set to true, try provided connection (from uri)

--debug  
--d

n/a

Print exception stack traces.

--help 
--h

n/a

Print the usage message.

--link
--l

uri

CDAP instance URI to interact with in the format     "[http[s]://]<hostname>[:<port>][/<path>]"
Defaults to "http://<hostname>.local:11015".

--namespace
--n

namespace_name

CDAP Instance Namespace to connect to. Defaults to “default”.

--retries
--r

number_of_retries

Set the number of times to retry contacting a service if it is determined to be unavailable. Defaults to 0.

--script
--s

script_name

Execute a file containing a series of CLI commands, line-by-line.

--timeout
--t

read_timeout_in_seconds

Set HTTP read timeout of the CLI in seconds.

--verify-ssl
--v

true|false

If "true", verify SSL certificate when making   requests. Defaults to "true".

Starting in CDAP 6.1.4, the option --uri is deprecated. Use --link option instead.

Settings

Certain commands (cli render asconnect-link, and use namespace) affect how the CLI works for the duration of a session.

  • The command cli render as <table-renderer> (from the General commands) sets how table data is rendered. Valid options are either alt (the default) or csv. Because the alt option might split a cell into multiple lines, you might need to use csv if you want to copy and paste the results into another application or include in a message.

    • With cli render as alt (the default), a command such as list apps will be output as:

      1 2 3 4 5 +================================+ | app id | description | +=============+==================+ | PurchaseApp | Some description | +=============+==================+
    • With cli render as csv, the same list apps will be output as:

      1 2 app id,description PurchaseApp,Some description
  • The command connect-link (from the General commands) allows you to connect to a CDAP instance.

  • The command use namespace (from the Namespace commands) allows you to set the namespace used with all subsequent commands. By default, all sessions start in the default namespace.