Index of dx commands
This page contains the help messages for each of the commands under dx, grouped by their primary category.

help

1
usage: dx help [-h] [command_or_category] [subcommand]
2
3
Displays the help message for the given command (and subcommand if given), or
4
displays the list of all commands in the given category.
5
6
CATEGORIES
7
8
all All commands
9
session Manage your login session
10
fs Navigate and organize your projects and files
11
data View, download, and upload data
12
metadata View and modify metadata for projects, data, and executions
13
workflow View and modify workflows
14
exec Manage and run apps, applets, and workflows
15
org Administer and operate on orgs
16
other Miscellaneous advanced utilities
17
18
EXAMPLE
19
20
To find all commands related to running and monitoring a job and then display
21
the help message for the command "run", run
22
23
$ dx help exec
24
<list of all execution-related dx commands>
25
$ dx help run
26
<help message for dx run>
27
28
positional arguments:
29
command_or_category Display the help message for the given command, or the
30
list of all available commands for the given category
31
subcommand Display the help message for the given subcommand of
32
the command
33
34
optional arguments:
35
-h, --help show this help message and exit
Copied!

Overriding environment variables

1
usage: dx command ... [--apiserver-host APISERVER_HOST]
2
[--apiserver-port APISERVER_PORT]
3
[--apiserver-protocol APISERVER_PROTOCOL]
4
[--project-context-id PROJECT_CONTEXT_ID]
5
[--workspace-id WORKSPACE_ID]
6
[--security-context SECURITY_CONTEXT]
7
[--auth-token AUTH_TOKEN]
8
9
optional arguments:
10
--apiserver-host APISERVER_HOST
11
API server host
12
--apiserver-port APISERVER_PORT
13
API server port
14
--apiserver-protocol APISERVER_PROTOCOL
15
API server protocol (http or https)
16
--project-context-id PROJECT_CONTEXT_ID
17
Default project or project context ID
18
--workspace-id WORKSPACE_ID
19
Workspace ID (for jobs only)
20
--security-context SECURITY_CONTEXT
21
JSON string of security context
22
--auth-token AUTH_TOKEN
23
Authentication token
Copied!

Category: session

Manage your login session

login

1
usage: dx login [-h] [--env-help] [--token TOKEN] [--noprojects] [--save]
2
[--timeout TIMEOUT]
3
4
Log in interactively and acquire credentials. Use "--token" to log in with an
5
existing API token.
6
7
optional arguments:
8
-h, --help show this help message and exit
9
--env-help Display help message for overriding environment variables
10
--token TOKEN Authentication token to use
11
--noprojects Do not print available projects
12
--save Save token and other environment variables for future
13
sessions
14
--timeout TIMEOUT Timeout for this login token (in seconds, or use suffix
15
s, m, h, d, w, M, y)
Copied!

logout

1
usage: dx logout [-h] [--env-help] [--host HOST] [--port PORT]
2
[--protocol PROTOCOL]
3
4
Log out and remove credentials
5
6
optional arguments:
7
-h, --help show this help message and exit
8
--env-help Display help message for overriding environment
9
variables
10
--host HOST Log out of the given auth server host (port must also
11
be given)
12
--port PORT Log out of the given auth server port (host must also
13
be given)
14
--protocol PROTOCOL Used in conjunction with host and port arguments, gives
15
the protocol to use when contacting auth server
Copied!

exit

1
usage: dx exit [-h]
2
3
Exit out of the interactive shell
4
5
optional arguments:
6
-h, --help show this help message and exit
Copied!

whoami

1
usage: dx whoami [-h] [--env-help] [--id]
2
3
Print the username of the current user, in the form "user-USERNAME"
4
5
optional arguments:
6
-h, --help show this help message and exit
7
--env-help Display help message for overriding environment variables
8
--id Print user ID instead of username
Copied!

env

1
usage: dx env [-h] [--env-help] [--bash] [--dx-flags]
2
3
Prints all environment variables in use as they have been resolved from
4
environment variables and configuration files. For more details, see
5
6
https://documentation.dnanexus.com/user/helpstrings-of-sdk-command-line-utilities#overriding-environment-variables
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment
11
variables
12
--bash Prints a list of bash commands to export the environment
13
variables
14
--dx-flags Prints the dx options to override the environment variables
Copied!

clearenv

1
usage: dx clearenv [-h] [--reset]
2
3
Clears all environment variables set by dx. More specifically, it removes
4
local state stored in ~/.dnanexus_config/environment. Does not affect the
5
environment variables currently set in your shell.
6
7
optional arguments:
8
-h, --help show this help message and exit
9
--reset Reset dx environment variables to empty values. Use this to
10
avoid interference between multiple dx sessions when using shell
11
environment variables.
Copied!

Category: fs

Navigate and organize your projects and files

ls

1
usage: dx ls [-h] [--color {off,on,auto}] [--delimiter [DELIMITER]]
2
[--env-help] [--brief | --verbose] [-a] [-l] [--obj] [--folders]
3
[--full]
4
[path]
5
6
List folders and/or objects in a folder
7
8
positional arguments:
9
path Folder (possibly in another project) to list the
10
contents of, default is the current directory in the
11
current project. Syntax: projectID:/folder/path
12
13
optional arguments:
14
-h, --help show this help message and exit
15
--color {off,on,auto}
16
Set when color is used (color=auto is used when stdout
17
is a TTY)
18
--delimiter [DELIMITER], --delim [DELIMITER]
19
Always use exactly one of DELIMITER to separate fields
20
to be printed; if no delimiter is provided with this
21
flag, TAB will be used
22
--env-help Display help message for overriding environment
23
variables
24
--brief Display a brief version of the return value; for most
25
commands, prints a DNAnexus ID per line
26
--verbose If available, displays extra verbose output
27
-a, --all show hidden files
28
-l, --long Alias for "verbose"
29
--obj show only objects
30
--folders show only folders
31
--full show full paths of folders
Copied!

tree

1
usage: dx tree [-h] [--color {off,on,auto}] [--env-help] [-a] [-l] [path]
2
3
List folders and objects in a tree
4
5
positional arguments:
6
path Folder (possibly in another project) to list the
7
contents of, default is the current directory in the
8
current project. Syntax: projectID:/folder/path
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--color {off,on,auto}
13
Set when color is used (color=auto is used when stdout
14
is a TTY)
15
--env-help Display help message for overriding environment
16
variables
17
-a, --all show hidden files
18
-l, --long use a long listing format
Copied!

pwd

1
usage: dx pwd [-h] [--env-help]
2
3
Print current working directory
4
5
optional arguments:
6
-h, --help show this help message and exit
7
--env-help Display help message for overriding environment variables
Copied!

select

1
usage: dx select [-h] [--env-help] [--name NAME]
2
[--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}] [--public]
3
[project]
4
5
Interactively list and select a project to switch to. By default, only lists
6
projects for which you have at least CONTRIBUTE permissions. Use --public to
7
see the list of public projects.
8
9
positional arguments:
10
project Name or ID of a project to switch to; if not provided
11
a list will be provided for you
12
13
optional arguments:
14
-h, --help show this help message and exit
15
--env-help Display help message for overriding environment
16
variables
17
--name NAME Name of the project (wildcard patterns supported)
18
--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}
19
Minimum level of permissions expected
20
--public Include ONLY public projects (will automatically set
21
--level to VIEW)
Copied!

cd

1
usage: dx cd [-h] [--env-help] [path]
2
3
Change the current working directory
4
5
positional arguments:
6
path Folder (possibly in another project) to which to change the
7
current working directory, default is "/" in the current project
8
9
optional arguments:
10
-h, --help show this help message and exit
11
--env-help Display help message for overriding environment variables
Copied!

cp

1
usage: dx cp [-h] [--env-help] [-a] source [source ...] destination
2
3
Copy objects and/or folders between different projects. Folders will
4
automatically be copied recursively. To specify which project to use as a
5
source or destination, prepend the path or ID of the object/folder with the
6
project ID or name and a colon.
7
8
EXAMPLES
9
10
The first example copies a file in a project called "FirstProj" to the
11
current directory of the current project. The second example copies the
12
object named "reads.fq.gz" in the current directory to the folder
13
/folder/path in the project with ID "project-B0VK6F6gpqG6z7JGkbqQ000Q",
14
and finally renaming it to "newname.fq.gz".
15
16
$ dx cp FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000q .
17
$ dx cp reads.fq.gz project-B0VK6F6gpqG6z7JGkbqQ000Q:/folder/path/newname.fq.gz
18
19
positional arguments:
20
source Objects and/or folder names to copy
21
destination Folder into which to copy the sources or new pathname (if only
22
one source is provided). Must be in a different
23
project/container than all source paths.
24
25
optional arguments:
26
-h, --help show this help message and exit
27
--env-help Display help message for overriding environment
28
variables
29
-a, --all Apply to all results with the same name without
30
prompting
Copied!

mv

1
usage: dx mv [-h] [--env-help] [-a] source [source ...] destination
2
3
Move or rename data objects and/or folders inside a single project. To copy
4
data between different projects, use 'dx cp' instead.
5
6
positional arguments:
7
source Objects and/or folder names to move
8
destination Folder into which to move the sources or new pathname (if only
9
one source is provided). Must be in the same project/container
10
as all source paths.
11
12
optional arguments:
13
-h, --help show this help message and exit
14
--env-help Display help message for overriding environment
15
variables
16
-a, --all Apply to all results with the same name without
17
prompting
Copied!

mkdir

1
usage: dx mkdir [-h] [--env-help] [-p] path [path ...]
2
3
Create a new folder
4
5
positional arguments:
6
path Paths to folders to create
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
11
-p, --parents no error if existing, create parent directories as needed
Copied!

rmdir

1
usage: dx rmdir [-h] [--env-help] path [path ...]
2
3
Remove a folder
4
5
positional arguments:
6
path Paths to folders to remove
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
Copied!

rm

1
usage: dx rm [-h] [--env-help] [-a] [-r] [-f] path [path ...]
2
3
Remove data objects and folders.
4
5
positional arguments:
6
path Paths to remove
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
11
-a, --all Apply to all results with the same name without prompting
12
-r, --recursive Recurse into a directory
13
-f, --force Force removal of files
Copied!

rmproject

1
usage: dx rmproject [-h] [--env-help] [-y] [-q] project [project ...]
2
3
Delete projects and all their associated data
4
5
positional arguments:
6
project Projects to remove
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
11
-y, --yes Do not ask for confirmation
12
-q, --quiet Do not print purely informational messages
Copied!

archive

1
usage: dx archive [-h] [-a] [-q] [--all-copies] [-y] [--no-recurse]
2
path [path ...]
3
4
Requests for the specified set files or for the files in a single specified folder in ONE project to be archived on the platform.
5
For each file, if this is the last copy of a file to have archival requested, it will trigger the full archival of the object.
6
Otherwise, the file will be marked in an archival state denoting that archival has been requested.
7
8
The input paths should be either 1 folder path or up to 1000 files, and all path(s) need to be in the same project.
9
To specify which project to use, prepend the path or ID of the file/folder with the project ID or name and a colon.
10
11
EXAMPLES:
12
13
# archive 3 files in project "FirstProj" with project ID project-B0VK6F6gpqG6z7JGkbqQ000Q
14
$ dx archive FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000Q FirstProj:/path/to/file1 project-B0VK6F6gpqG6z7JGkbqQ000Q:/file2
15
16
# archive 2 files in current project. Specifying file ids saves time by avoiding file name resolution.
17
$ dx select FirstProj
18
$ dx archive file-A00000ygpqGK8ZPjbk0Q000Q file-B00000ygpqGK8ZPjbk0Q000Q
19
20
# archive all files recursively in project-B0VK6F6gpqG6z7JGkbqQ000Q
21
$ dx archive project-B0VK6F6gpqG6z7JGkbqQ000Q:/
22
23
24
positional arguments:
25
path May refer to a single folder or specify up to 1000
26
files inside a project.
27
28
optional arguments:
29
-h, --help show this help message and exit
30
-a, --all Apply to all results with the same name without
31
prompting
32
-q, --quiet Do not print extra info messages
33
--all-copies If true, archive all the copies of files in projects
34
with the same billTo org.
35
See https://documentation.dnanexus.com/developer/api/d
36
ata-containers/projects#api-method-project-xxxx-archiv
37
e for details.
38
-y, --yes Do not ask for confirmation.
39
--no-recurse When `path` refers to a single folder, this flag
40
causes only files in the specified folder and not its
41
subfolders to be archived. This flag has no impact
42
when `path` input refers to a collection of files.
43
44
Output:
45
If -q option is not specified, prints "Tagged <count> file(s) for archival"
Copied!

unarchive

1
usage: dx unarchive [-h] [-a] [--rate {Expedited,Standard,Bulk}] [-q] [-y]
2
[--no-recurse]
3
path [path ...]
4
5
Requests for a specified set files or for the files in a single specified folder in ONE project to be unarchived on the platform.
6
The requested copy will eventually be transitioned over to the live state while all other copies will move over to the archival state.
7
8
The input paths should be either 1 folder path or up to 1000 files, and all path(s) need to be in the same project.
9
To specify which project to use, prepend the path or ID of the file/folder with the project ID or name and a colon.
10
11
EXAMPLES:
12
13
# unarchive 3 files in project "FirstProj" with project ID project-B0VK6F6gpqG6z7JGkbqQ000Q
14
$ dx unarchive FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000Q FirstProj:/path/to/file1 project-B0VK6F6gpqG6z7JGkbqQ000Q:/file2
15
16
# unarchive 2 files in current project. Specifying file ids saves time by avoiding file name resolution.
17
$ dx select FirstProj
18
$ dx unarchive file-A00000ygpqGK8ZPjbk0Q000Q file-B00000ygpqGK8ZPjbk0Q000Q
19
20
# unarchive all files recursively in project-B0VK6F6gpqG6z7JGkbqQ000Q
21
$ dx unarchive project-B0VK6F6gpqG6z7JGkbqQ000Q:/
22
23
24
positional arguments:
25
path May refer to a single folder or specify up to 1000
26
files inside a project.
27
28
optional arguments:
29
-h, --help show this help message and exit
30
-a, --all Apply to all results with the same name without
31
prompting
32
--rate {Expedited,Standard,Bulk}
33
The speed at which all files in this request are
34
unarchived.
35
- Azure regions: {Expedited, Standard}
36
- AWS regions: {Expedited, Standard, Bulk}
37
-q, --quiet Do not print extra info messages
38
-y, --yes Do not ask for confirmation.
39
--no-recurse When `path` refers to a single folder, this flag
40
causes only files in the specified folder and not its
41
subfolders to be unarchived. This flag has no impact
42
when `path` input refers to a collection of files.
43
44
Output:
45
If -q option is not specified, prints "Tagged <> file(s) for unarchival, totalling <> GB, costing <> "
Copied!

Category: data

View, download, and upload data

describe

1
usage: dx describe [-h] [--json] [--color {off,on,auto}]
2
[--delimiter [DELIMITER]] [--env-help] [--details]
3
[--verbose] [--name] [--multi]
4
path
5
6
Describe a DNAnexus entity. Use this command to describe data objects by name
7
or ID, jobs, apps, users, organizations, etc. If using the "--json" flag, it
8
will thrown an error if more than one match is found (but if you would like a
9
JSON array of the describe hashes of all matches, then provide the "--multi"
10
flag). Otherwise, it will always display all results it finds.
11
12
NOTES:
13
14
- The project found in the path is used as a HINT when you are using an object
15
ID; you may still get a result if you have access to a copy of the object in
16
some other project, but if it exists in the specified project, its description
17
will be returned.
18
19
- When describing apps or applets, options marked as advanced inputs will be
20
hidden unless --verbose is provided
21
22
positional arguments:
23
path Object ID or path to an object (possibly in another
24
project) to describe.
25
26
optional arguments:
27
-h, --help show this help message and exit
28
--json Display return value in JSON
29
--color {off,on,auto}
30
Set when color is used (color=auto is used when stdout
31
is a TTY)
32
--delimiter [DELIMITER], --delim [DELIMITER]
33
Always use exactly one of DELIMITER to separate fields
34
to be printed; if no delimiter is provided with this
35
flag, TAB will be used
36
--env-help Display help message for overriding environment
37
variables
38
--details Include details of data objects
39
--verbose Include all possible metadata
40
--name Only print the matching names, one per line
41
--multi If the flag --json is also provided, then returns a
42
JSON array of describe hashes of all matching results
Copied!

upload

1
usage: dx upload [-h] [--visibility {hidden,visible}] [--property KEY=VALUE]
2
[--type TYPE] [--tag TAG] [--details DETAILS] [-p]
3
[--brief | --verbose] [--env-help] [--path [PATH]] [-r]
4
[--wait] [--no-progress] [--buffer-size WRITE_BUFFER_SIZE]
5
[--singlethread]
6
filename [filename ...]
7
8
Upload local file(s) or directory. If "-" is provided, stdin will be used
9
instead. By default, the filename will be used as its new name. If
10
--path/--destination is provided with a path ending in a slash, the filename
11
will be used, and the folder path will be used as a destination. If it does
12
not end in a slash, then it will be used as the final name.
13
14
positional arguments:
15
filename Local file or directory to upload ("-" indicates stdin
16
input); provide multiple times to upload multiple
17
files or directories
18
19
optional arguments:
20
-h, --help show this help message and exit
21
--brief Display a brief version of the return value; for most
22
commands, prints a DNAnexus ID per line
23
--verbose If available, displays extra verbose output
24
--env-help Display help message for overriding environment
25
variables
26
--path [PATH], --destination [PATH]
27
DNAnexus path to upload file(s) to (default uses
28
current project and folder if not provided)
29
-r, --recursive Upload directories recursively
30
--wait Wait until the file has finished closing
31
--no-progress Do not show a progress bar
32
--buffer-size WRITE_BUFFER_SIZE
33
Set the write buffer size (in bytes)
34
--singlethread Enable singlethreaded uploading
35
36
metadata arguments:
37
--visibility {hidden,visible}
38
Whether the object is hidden or not
39
--property KEY=VALUE Key-value pair to add as a property; repeat as
40
necessary, e.g. "--property key1=val1 --property
41
key2=val2"
42
--type TYPE Type of the data object; repeat as necessary, e.g. "--
43
type type1 --type type2"
44
--tag TAG Tag of the data object; repeat as necessary, e.g. "--
45
tag tag1 --tag tag2"
46
--details DETAILS JSON to store as details
47
-p, --parents Create any parent folders necessary
Copied!

download

1
usage: dx download [-h] [--env-help] [-o OUTPUT] [-f] [-r] [-a]
2
[--no-progress] [--lightweight] [--unicode]
3
path [path ...]
4
5
Download the contents of a file object or multiple objects. Use "-o -" to
6
direct the output to stdout.
7
8
positional arguments:
9
path Data object ID or name, or folder to download
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--env-help Display help message for overriding environment
14
variables
15
-o OUTPUT, --output OUTPUT
16
Local filename or directory to be used ("-" indicates
17
stdout output); if not supplied or a directory is
18
given, the object's name on the platform will be used,
19
along with any applicable extensions
20
-f, --overwrite Resume an interupted download if the local and remote
21
file signatures match. If the signatures do not match
22
the local file will be overwritten.
23
-r, --recursive Download folders recursively
24
-a, --all If multiple objects match the input, download all of
25
them
26
--no-progress Do not show a progress bar
27
--lightweight Skip some validation steps to make fewer API calls
28
--unicode Display the characters as text/unicode when writing to
29
stdout
Copied!

make_download_url

1
usage: dx make_download_url [-h] [--duration DURATION] [--filename FILENAME]
2
path
3
4
Creates a pre-authenticated link that can be used to download a file without
5
logging in.
6
7
positional arguments:
8
path Data object ID or name to access
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--duration DURATION Time for which the URL will remain valid (in seconds,
13
or use suffix s, m, h, d, w, M, y). Default: 1 day
14
--filename FILENAME Name that the server will instruct the client to save
15
the file as (default is the filename)
Copied!

cat

1
usage: dx cat [-h] [--env-help] [--unicode] path [path ...]
2
3
positional arguments:
4
path File ID or name(s) to print to stdout
5
6
optional arguments:
7
-h, --help show this help message and exit
8
--env-help Display help message for overriding environment variables
9
--unicode Display the characters as text/unicode when writing to stdout
Copied!

head

1
usage: dx head [-h] [--color {off,on,auto}] [--env-help] [-n N] path
2
3
Print the first part of a file. By default, prints the first 10 lines.
4
5
positional arguments:
6
path File ID or name to access
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--color {off,on,auto}
11
Set when color is used (color=auto is used when stdout
12
is a TTY)
13
--env-help Display help message for overriding environment
14
variables
15
-n N, --lines N Print the first N lines (default 10)
Copied!

new

1
usage: dx new [-h] class ...
2
3
Use this command with one of the available subcommands (classes) to create a
4
new project or data object from scratch. Not all data types are supported. See
5
'dx upload' for files and 'dx build' for applets.
6
7
positional arguments:
8
class
9
user Create a new user account
10
org Create new non-billable org
11
project Create a new project
12
record Create a new record
13
workflow Create a new workflow
14
15
optional arguments:
16
-h, --help show this help message and exit
Copied!

new project

1
usage: dx new project [-h] [--brief | --verbose] [--env-help]
2
[--region REGION] [-s] [--bill-to BILL_TO] [--phi]
3
[--database-ui-view-only]
4
[name]
5
6
Create a new project
7
8
positional arguments:
9
name Name of the new project
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--brief Display a brief version of the return value; for most
14
commands, prints a DNAnexus ID per line
15
--verbose If available, displays extra verbose output
16
--env-help Display help message for overriding environment
17
variables
18
--region REGION Region affinity of the new project
19
-s, --select Select the new project as current after creating
20
--bill-to BILL_TO ID of the user or org to which the project will be
21
billed. The default value is the billTo of the
22
requesting user.
23
--phi Add PHI protection to project
24
--database-ui-view-only
25
If set to true, viewers of the project will not be
26
able to access database data directly
Copied!

new record

1
usage: dx new record [-h] [--visibility {hidden,visible}]
2
[--property KEY=VALUE] [--type TYPE] [--tag TAG]
3
[--details DETAILS] [-p] [--brief | --verbose]
4
[--env-help] [--init INIT] [--close]
5
[path]
6
7
Create a new record
8
9
positional arguments:
10
path DNAnexus path for the new data object (default uses
11
current project and folder if not provided)
12
13
optional arguments:
14
-h, --help show this help message and exit
15
--brief Display a brief version of the return value; for most
16
commands, prints a DNAnexus ID per line
17
--verbose If available, displays extra verbose output
18
--env-help Display help message for overriding environment
19
variables
20
--init INIT Path to record from which to initialize all metadata
21
--close Close the record immediately after creating it
22
23
metadata arguments:
24
--visibility {hidden,visible}
25
Whether the object is hidden or not
26
--property KEY=VALUE Key-value pair to add as a property; repeat as
27
necessary,
28
e.g. "--property key1=val1 --property key2=val2"
29
--type TYPE Type of the data object; repeat as necessary,
30
e.g. "--type type1 --type type2"
31
--tag TAG Tag of the data object; repeat as necessary,
32
e.g. "--tag tag1 --tag tag2"
33
--details DETAILS JSON to store as details
34
-p, --parents Create any parent folders necessary
Copied!

new workflow

1
usage: dx new workflow [-h] [--visibility {hidden,visible}]
2
[--property KEY=VALUE] [--type TYPE] [--tag TAG]
3
[--details DETAILS] [-p] [--brief | --verbose]
4
[--env-help] [--title TITLE] [--summary SUMMARY]
5
[--description DESCRIPTION]
6
[--output-folder OUTPUT_FOLDER] [--init INIT]
7
[path]
8
9
Create a new workflow
10
11
positional arguments:
12
path DNAnexus path for the new data object (default uses
13
current project and folder if not provided)
14
15
optional arguments:
16
-h, --help show this help message and exit
17
--brief Display a brief version of the return value; for most
18
commands, prints a DNAnexus ID per line
19
--verbose If available, displays extra verbose output
20
--env-help Display help message for overriding environment
21
variables
22
--title TITLE Workflow title
23
--summary SUMMARY Workflow summary
24
--description DESCRIPTION
25
Workflow description
26
--output-folder OUTPUT_FOLDER
27
Default output folder for the workflow
28
--init INIT Path to workflow or an analysis ID from which to
29
initialize all metadata
30
31
metadata arguments:
32
--visibility {hidden,visible}
33
Whether the object is hidden or not
34
--property KEY=VALUE Key-value pair to add as a property; repeat as
35
necessary,
36
e.g. "--property key1=val1 --property key2=val2"
37
--type TYPE Type of the data object; repeat as necessary,
38
e.g. "--type type1 --type type2"
39
--tag TAG Tag of the data object; repeat as necessary,
40
e.g. "--tag tag1 --tag tag2"
41
--details DETAILS JSON to store as details
42
-p, --parents Create any parent folders necessary
Copied!

close

1
usage: dx close [-h] [--env-help] [-a] [--wait] path [path ...]
2
3
Close a remote data object or set of objects.
4
5
positional arguments:
6
path Path to a data object to close
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
11
-a, --all Apply to all results with the same name without prompting
12
--wait Wait for the object(s) to close
Copied!

wait

1
usage: dx wait [-h] [--env-help] [--from-file] path [path ...]
2
3
Polls the state of specified data object(s) or job(s) until they are all in
4
the desired state. Waits until the "closed" state for a data object, and for
5
any terminal state for a job ("terminated", "failed", or "done"). Exits with a
6
non-zero code if a job reaches a terminal state that is not "done". Can also
7
provide a local file containing a list of data object(s) or job(s), one per
8
line; the file will be read if "--from-file" argument is added.
9
10
positional arguments:
11
path Path to a data object, job ID, or file with IDs to wait for
12
13
optional arguments:
14
-h, --help show this help message and exit
15
--env-help Display help message for overriding environment variables
16
--from-file Read the list of objects to wait for from the file provided in
17
path
Copied!

get

1
usage: dx get [-h] [--env-help] [-o OUTPUT] [--filename FILENAME]
2
[--allow-all-files] [--recurse] [--no-ext] [--omit-resources]
3
[-f]
4
path
5
6
Download the contents of some types of data (records, apps, applets,
7
workflows, files, and databases). Downloading an app, applet or a workflow
8
will attempt to reconstruct a source directory that can be used to rebuild it
9
with "dx build". Use "-o -" to direct the output to stdout.
10
11
positional arguments:
12
path Data object ID or name to access
13
14
optional arguments:
15
-h, --help show this help message and exit
16
--env-help Display help message for overriding environment
17
variables
18
-o OUTPUT, --output OUTPUT
19
local file path where the data is to be saved ("-"
20
indicates stdout output for objects of class file and
21
record). If not supplied, the object's name on the
22
platform will be used, along with any applicable
23
extensions. For app(let) and workflow objects, if
24
OUTPUT does not exist, the object's source directory
25
will be created there; if OUTPUT is an existing
26
directory, a new directory with the object's name will
27
be created inside it.
28
--filename FILENAME When downloading from a database, name of the file or
29
folder to be downloaded. If omitted, all files in the
30
database will be downloaded, so use caution and
31
include the --allow-all-files argument.
32
--allow-all-files When downloading from a database, this allows all
33
files in a database to be downloaded when --filename
34
argument is omitted.
35
--recurse When downloading from a database, look for files
36
recursively down the directory structure. Otherwise,
37
by default, only look on one level.
38
--no-ext If -o is not provided, do not add an extension to the
39
filename
40
--omit-resources When downloading an app(let), omit fetching the
41
resources associated with the app(let).
42
-f, --overwrite Overwrite the local file if necessary
Copied!

find data

1
usage: dx find data [-h] [--brief | --verbose] [--json]
2
[--color {off,on,auto}] [--delimiter [DELIMITER]]
3
[--env-help] [--property KEY[=VALUE]] [--tag TAG]
4
[--class {record,file,applet,workflow,database}]
5
[--state {open,closing,closed,any}]
6
[--visibility {hidden,visible,either}] [--name NAME]
7
[--type TYPE] [--link LINK] [--all-projects]
8
[--path PROJECT:FOLDER] [--norecurse]
9
[--created-after CREATED_AFTER]
10
[--created-before CREATED_BEFORE] [--mod-after MOD_AFTER]
11
[--mod-before MOD_BEFORE] [--region REGION]
12
13
Finds data objects subject to the given search parameters. By default,
14
restricts the search to the current project if set. To search over all
15
projects (excluding public projects), use --all-projects (overrides --path and
16
--norecurse).
17
18
optional arguments:
19
-h, --help show this help message and exit
20
--brief Display a brief version of the return value; for most
21
commands, prints a DNAnexus ID per line
22
--verbose If available, displays extra verbose output
23
--json Display return value in JSON
24
--color {off,on,auto}
25
Set when color is used (color=auto is used when stdout
26
is a TTY)
27
--delimiter [DELIMITER], --delim [DELIMITER]
28
Always use exactly one of DELIMITER to separate fields
29
to be printed; if no delimiter is provided with this
30
flag, TAB will be used
31
--env-help Display help message for overriding environment
32
variables
33
--property KEY[=VALUE]
34
Key-value pair of a property or simply a property key;
35
if only a key is provided, matches a result that has
36
the key with any value; repeat as necessary, e.g. "--
37
property key1=val1 --property key2"
38
--tag TAG Tag to match; repeat as necessary, e.g. "--tag tag1
39
--tag tag2" will require both tags
40
--class {record,file,applet,workflow,database}
41
Data object class
42
--state {open,closing,closed,any}
43
State of the object
44
--visibility {hidden,visible,either}
45
Whether the object is hidden or not
46
--name NAME Name of the object
47
--type TYPE Type of the data object
48
--link LINK Object ID that the data object links to
49
--all-projects, --allprojects
50
Extend search to all projects (excluding public
51
projects)
52
--path PROJECT:FOLDER
53
Project and/or folder in which to restrict the results
54
--norecurse Do not recurse into subfolders
55
--created-after CREATED_AFTER
56
Date (e.g. 2012-01-01) or integer timestamp after
57
which the object was created (negative number means ms
58
in the past, or use suffix s, m, h, d, w, M, y)
59
Negative input example "--created-after=-2d"
60
--created-before CREATED_BEFORE
61
Date (e.g. 2012-01-01) or integer timestamp before
62
which the object was created (negative number means ms
63
in the past, or use suffix s, m, h, d, w, M, y)
64
Negative input example "--created-before=-2d"
65
--mod-after MOD_AFTER
66
Date (e.g. 2012-01-01) or integer timestamp after
67
which the object was last modified (negative number
68
means ms in the past, or use suffix s, m, h, d, w, M,
69
y) Negative input example "--mod-after=-2d"
70
--mod-before MOD_BEFORE
71
Date (e.g. 2012-01-01) or integer timestamp before
72
which the object was last modified (negative number
73
means ms in the past, or use suffix s, m, h, d, w, M,
74
y) Negative input example "--mod-before=-2d"
75
--region REGION Restrict the search to the provided region
Copied!

find projects

1
usage: dx find projects [-h] [--brief | --verbose] [--json]
2
[--delimiter [DELIMITER]] [--env-help]
3
[--property KEY[=VALUE]] [--tag TAG]
4
[--phi {true,false}] [--name NAME]
5
[--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}]
6
[--public] [--created-after CREATED_AFTER]
7
[--created-before CREATED_BEFORE] [--region REGION]
8
9
Finds projects subject to the given search parameters. Use the --public flag
10
to list all public projects.
11
12
optional arguments:
13
-h, --help show this help message and exit
14
--brief Display a brief version of the return value; for most
15
commands, prints a DNAnexus ID per line
16
--verbose If available, displays extra verbose output
17
--json Display return value in JSON
18
--delimiter [DELIMITER], --delim [DELIMITER]
19
Always use exactly one of DELIMITER to separate fields
20
to be printed; if no delimiter is provided with this
21
flag, TAB will be used
22
--env-help Display help message for overriding environment
23
variables
24
--property KEY[=VALUE]
25
Key-value pair of a property or simply a property key;
26
if only a key is provided, matches a result that has
27
the key with any value; repeat as necessary, e.g. "--
28
property key1=val1 --property key2"
29
--tag TAG Tag to match; repeat as necessary, e.g. "--tag tag1
30
--tag tag2" will require both tags
31
--phi {true,false} If set to true, only projects that contain PHI data
32
will be retrieved. If set to false, only projects that
33
do not contain PHI data will be retrieved.
34
--name NAME Name of the project
35
--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}
36
Minimum level of permissions expected
37
--public Include ONLY public projects (will automatically set
38
--level to VIEW)
39
--created-after CREATED_AFTER
40
Date (e.g. 2012-01-01) or integer timestamp after
41
which the project was created (negative number means
42
ms in the past, or use suffix s, m, h, d, w, M, y)
43
Negative input example "--created-after=-2d"
44
--created-before CREATED_BEFORE
45
Date (e.g. 2012-01-01) or integer timestamp after
46
which the project was created (negative number means
47
ms in the past, or use suffix s, m, h, d, w, M, y)
48
Negative input example "--created-before=-2d"
49
--region REGION Restrict the search to the provided region
Copied!

Category: metadata

View and modify metadata for projects and data objects
See also dx describe and dx close.

set_details

1
usage: dx set_details [-h] [--env-help] [-a] [-f DETAILS_FILE] path [details]
2
3
Set the JSON details of a data object.
4
5
positional arguments:
6
path ID or path to data object to modify
7
details JSON to store as details
8
9
optional arguments:
10
-h, --help show this help message and exit
11
--env-help Display help message for overriding environment
12
variables
13
-a, --all Apply to all results with the same name without
14
prompting
15
-f DETAILS_FILE, --details-file DETAILS_FILE
16
Path to local file containing JSON to store as details
Copied!

get_details

1
usage: dx get_details [-h] [--env-help] path
2
3
Get the JSON details of a data object.
4
5
positional arguments:
6
path ID or path to data object to get details for
7
8
optional arguments:
9
-h, --help show this help message and exit
10
--env-help Display help message for overriding environment variables
Copied!

set_visibility

1
usage: dx set_visibility [-h] [--env-help] [-a] path {hidden,visible}
2
3
Set visibility on a data object.
4
5
positional arguments:
6
path ID or path to data object to modify
7
{hidden,visible} Visibility that the object should have
8
9
optional arguments:
10
-h, --help show this help message and exit
11
--env-help Display help message for overriding environment variables
12
-a, --all Apply to all results with the same name without prompting
Copied!

add_types

1
usage: dx add_types [-h] [--env-help] [-a] path type [type ...]
2
3
Add types to a data object. See
4
https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types
5
for a list of DNAnexus types.
6
7
positional arguments:
8
path ID or path to data object to modify
9
type Types to add
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--env-help Display help message for overriding environment variables
14
-a, --all Apply to all results with the same name without prompting
Copied!

remove_types

1
usage: dx remove_types [-h] [--env-help] [-a] path type [type ...]
2
3
Remove types from a data object. See
4
https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types
5
for a list of DNAnexus types.
6
7
positional arguments:
8
path ID or path to data object to modify
9
type Types to remove
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--env-help Display help message for overriding environment variables
14
-a, --all Apply to all results with the same name without prompting
Copied!

tag

1
usage: dx tag [-h] [--env-help] [-a] path tag [tag ...]
2
3
Tag a project, data object, or execution. Note that a project context must be
4
either set or specified for data object IDs or paths.
5
6
positional arguments:
7
path ID or path to project, data object, or execution to modify
8
tag Tags to add
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--env-help Display help message for overriding environment variables
13
-a, --all Apply to all results with the same name without prompting
Copied!

untag

1
usage: dx untag [-h] [--env-help] [-a] path tag [tag ...]
2
3
Untag a project, data object, or execution. Note that a project context must
4
be either set or specified for data object IDs or paths.
5
6
positional arguments:
7
path ID or path to project, data object, or execution to modify
8
tag Tags to remove
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--env-help Display help message for overriding environment variables
13
-a, --all Apply to all results with the same name without prompting
Copied!

rename

1
usage: dx rename [-h] [--env-help] [-a] path name
2
3
Rename a project or data object. To rename folders, use 'dx mv' instead. Note
4
that a project context must be either set or specified to rename a data
5
object. To specify a project or a project context, append a colon character
6
":" after the project ID or name.
7
8
positional arguments:
9
path Path to project or data object to rename
10
name New name
11
12
optional arguments:
13
-h, --help show this help message and exit
14
--env-help Display help message for overriding environment variables
15
-a, --all Apply to all results with the same name without prompting
Copied!

set_properties

1
usage: dx set_properties [-h] [--env-help] [-a]
2
path propertyname=value [propertyname=value ...]
3
4
Set properties of a project, data object, or execution. Note that a project
5
context must be either set or specified for data object IDs or paths.
6
7
positional arguments:
8
path ID or path to project, data object, or execution to
9
modify
10
propertyname=value Key-value pairs of property names and their new values
11
12
optional arguments:
13
-h, --help show this help message and exit
14
--env-help Display help message for overriding environment
15
variables
16
-a, --all Apply to all results with the same name without
17
prompting
Copied!

unset_properties

1
usage: dx unset_properties [-h] [--env-help] [-a]
2
path propertyname [propertyname ...]
3
4
Unset properties of a project, data object, or execution. Note that a project
5
context must be either set or specified for data object IDs or paths.
6
7
positional arguments:
8
path ID or path to project, data object, or execution to modify
9
propertyname Property names to unset
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--env-help Display help message for overriding environment variables
14
-a, --all Apply to all results with the same name without prompting
Copied!

Category: exec

Manage and run your apps, applets, and workflows

build

1
usage: dx build [-h] [--env-help] [--brief | --verbose] [--ensure-upload]
2
[--force-symlinks] [--app] [--workflow] [--globalworkflow]
3
[-d DESTINATION] [--dry-run] [--publish] [--from _FROM]
4
[--remote] [--no-watch] [-f] [-a] [-v VERSION]
5
[-b USER_OR_ORG] [--no-check-syntax]
6
[--no-version-autonumbering] [--no-update]
7
[--no-dx-toolkit-autodep] [--no-parallel-build] [-y]
8
[--extra-args EXTRA_ARGS] [--run ...] [--region REGION]
9
[--keep-open]
10
[src_dir]
11
12
Build an applet, app, or workflow object from a local source directory or an
13
app from an existing applet in the platform. You can use dx-app-wizard to
14
generate a skeleton directory of an app/applet with the necessary files.
15
16
positional arguments:
17
src_dir App, applet, or workflow source directory (default:
18
current directory)
19
20
optional arguments:
21
-h, --help show this help message and exit
22
--env-help Display help message for overriding environment
23
variables
24
--brief Display a brief version of the return value; for most
25
commands, prints a DNAnexus ID per line
26
--verbose If available, displays extra verbose output
27
--ensure-upload If specified, will bypass computing checksum of
28
resources directory and upload it unconditionally; by
29
default, will compute checksum and upload only if it
30
differs from a previously uploaded resources bundle.
31
--force-symlinks If specified, will not attempt to dereference symbolic
32
links pointing outside of the resource directory. By
33
default, any symlinks within the resource directory
34
are kept as links while links to files outside the
35
resource directory are dereferenced (note that links
36
to directories outside of the resource directory will
37
cause an error).
38
--app, --create-app Create an app.
39
--workflow, --create-workflow
40
Create a workflow.
41
--globalworkflow, --create-globalworkflow
42
Create a global workflow.
43
--dry-run, -n Do not create an app(let): only perform local checks
44
and compilation steps, and show the spec of the
45
app(let) that would have been created.
46
--remote Build the app remotely by uploading the source
47
directory to the DNAnexus Platform and building it
48
there. This option is useful if you would otherwise
49
need to cross-compile the app(let) to target the
50
Execution Environment.
51
--no-watch Don't watch the real-time logs of the remote builder.
52
(This option only applicable if --remote was
53
specified).
54
-v VERSION, --version VERSION
55
Override the version number supplied in the manifest.
56
--no-check-syntax Warn but do not fail when syntax problems are found
57
(default is to fail on such errors)
58
--no-dx-toolkit-autodep
59
Do not auto-insert the dx-toolkit dependency (default
60
is to add it if it would otherwise be absent from the
61
runSpec)
62
--no-parallel-build Build with make instead of make -jN.
63
--extra-args EXTRA_ARGS
64
Arguments (in JSON format) to pass to the /applet/new
65
API method, overriding all other settings
66
--run ... Run the app or applet after building it (options
67
following this are passed to dx run; run at high
68
priority by default)
69
--keep-open Do not close workflow after building it. Cannot be
70
used when building apps, applets or global workflows.
71
72
options for creating apps:
73
(Only valid when --app/--create-app is specified)
74
75
--publish Publish the resulting app and make it the default.
76
--from _FROM ID of an applet to create an app from. Source
77
directory cannot be given with this option
78
-b USER_OR_ORG, --bill-to USER_OR_ORG
79
Entity (of the form user-NAME or org-ORGNAME) to bill
80
for the app.
81
--no-version-autonumbering
82
Only attempt to create the version number supplied in
83
the manifest (that is, do not try to create an
84
autonumbered version such as 1.2.3+git.ab1b1c1d if
85
1.2.3 already exists and is published).
86
--no-update Never update an existing unpublished app in place.
87
-y, --yes Do not ask for confirmation for potentially dangerous
88
operations
89
--region REGION Enable the app in this region. This flag can be
90
specified multiple times to enable the app in multiple
91
regions. If --region is not specified, then the
92
enabled region(s) will be determined by
93
'regionalOptions' in dxapp.json, or the project
94
context.
95
96
options for creating applets or workflows:
97
(Only valid when --app/--create-app is NOT specified)
98
99
-d DESTINATION, --destination DESTINATION
100
Specifies the destination project, destination folder,
101
and/or name for the applet, in the form
102
[PROJECT_NAME_OR_ID:][/[FOLDER/][NAME]]. Overrides the
103
project, folder, and name fields of the dxapp.json or
104
dxworkflow.json, if they were supplied.
105
-f, --overwrite Remove existing applet(s) of the same name in the
106
destination folder. This option is not yet supported
107
for workflows.
108
-a, --archive Archive existing applet(s) of the same name in the
109
destination folder. This option is not yet supported
110
for workflows.
Copied!

add users

1
usage: dx add users [-h] [--env-help] app authorizedUser [authorizedUser ...]
2
3
Add users or orgs to the list of authorized users of an app. Published
4
versions of the app will only be accessible to users represented by this list
5
and to developers of the app. Unpublished versions are restricted to the
6
developers.
7
8
positional arguments:
9
app Name or ID of an app
10
authorizedUser One or more users or orgs to add
11
12
optional arguments:
13
-h, --help show this help message and exit
14
--env-help Display help message for overriding environment variables
Copied!

add developers

1
usage: dx add developers [-h] [--env-help] app developer [developer ...]
2
3
Add users or orgs to the list of developers for an app. Developers are able to
4
build and publish new versions of the app, and add or remove others from the
5
list of developers and authorized users.
6
7
positional arguments:
8
app Name or ID of an app
9
developer One or more users or orgs to add
10
11
optional arguments:
12
-h, --help show this help message and exit
13
--env-help Display help message for overriding environment variables
Copied!

list users

1
usage: dx list users [-h] [--env-help] app
2
3
List the authorized users of an app. Published versions of the app will only
4
be accessible to users represented by this list and to developers of the app.
5
Unpublished versions are restricted to the developers
6
7
positional arguments:
8
app Name or ID of an app
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--env-help Display help message for overriding environment variables
Copied!

list developers

1
usage: dx list developers [-h] [--env-help] app
2
3
List the developers for an app. Developers are able to build and publish new
4
versions of the app, and add or remove others from the list of developers and
5
authorized users.
6
7
positional arguments:
8
app Name or ID of an app
9
10
optional arguments:
11
-h, --help show this help message and exit
12
--env-help Display help message for overriding environment variables
Copied!

remove users

1
usage: dx remove users [-h] [--env-help]
2
app authorizedUser [authorizedUser ...]
3
4
Remove users or orgs from the list of authorized users of an app. Published
5
versions of the app will only be accessible to users represented by this list
6
and to developers of the app. Unpublished versions are restricted to the
7
developers
8
9
positional arguments:
10
app Name or ID of an app
11
authorizedUser One or more users or orgs to remove
12
13
optional arguments:
14
-h, --help show this help message and exit
15
--env-help Display help message for overriding environment variables
Copied!

remove developers

1
usage: dx remove developers [-h] [--env-help] app developer [developer ...]
2