Index of dx commands
This page contains the help messages for each of the commands under dx, grouped by their primary category.
usage: dx help [-h] [command_or_category] [subcommand]
Displays the help message for the given command (and subcommand if given), or
displays the list of all commands in the given category.
CATEGORIES
all All commands
session Manage your login session
fs Navigate and organize your projects and files
data View, download, and upload data
metadata View and modify metadata for projects, data, and executions
workflow View and modify workflows
exec Manage and run apps, applets, and workflows
org Administer and operate on orgs
other Miscellaneous advanced utilities
EXAMPLE
To find all commands related to running and monitoring a job and then display
the help message for the command "run", run
$ dx help exec
<list of all execution-related dx commands>
$ dx help run
<help message for dx run>
positional arguments:
command_or_category Display the help message for the given command, or the
list of all available commands for the given category
subcommand Display the help message for the given subcommand of
the command
optional arguments:
-h, --help show this help message and exit
usage: dx command ... [--apiserver-host APISERVER_HOST]
[--apiserver-port APISERVER_PORT]
[--apiserver-protocol APISERVER_PROTOCOL]
[--project-context-id PROJECT_CONTEXT_ID]
[--workspace-id WORKSPACE_ID]
[--security-context SECURITY_CONTEXT]
[--auth-token AUTH_TOKEN]
optional arguments:
--apiserver-host APISERVER_HOST
API server host
--apiserver-port APISERVER_PORT
API server port
--apiserver-protocol APISERVER_PROTOCOL
API server protocol (http or https)
--project-context-id PROJECT_CONTEXT_ID
Default project or project context ID
--workspace-id WORKSPACE_ID
Workspace ID (for jobs only)
--security-context SECURITY_CONTEXT
JSON string of security context
--auth-token AUTH_TOKEN
Authentication token
Manage your login session.
usage: dx login [-h] [--env-help] [--token TOKEN] [--noprojects] [--save]
[--timeout TIMEOUT]
Log in interactively and acquire credentials. Use "--token" to log in with an
existing API token.
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
--token TOKEN Authentication token to use
--noprojects Do not print available projects
--save Save token and other environment variables for future
sessions
--timeout TIMEOUT Timeout for this login token (in seconds, or use suffix
s, m, h, d, w, M, y)
usage: dx logout [-h] [--env-help] [--host HOST] [--port PORT]
[--protocol PROTOCOL]
Log out and remove credentials
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
--host HOST Log out of the given auth server host (port must also
be given)
--port PORT Log out of the given auth server port (host must also
be given)
--protocol PROTOCOL Used in conjunction with host and port arguments, gives
the protocol to use when contacting auth server
usage: dx exit [-h]
Exit out of the interactive shell
optional arguments:
-h, --help show this help message and exit
usage: dx whoami [-h] [--env-help] [--id]
Print the username of the current user, in the form "user-USERNAME"
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
--id Print user ID instead of username
usage: dx env [-h] [--env-help] [--bash] [--dx-flags]
Prints all environment variables in use as they have been resolved from
environment variables and configuration files. For more details, see
https://documentation.dnanexus.com/user/helpstrings-of-sdk-command-line-utilities#overriding-environment-variables
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
--bash Prints a list of bash commands to export the environment
variables
--dx-flags Prints the dx options to override the environment variables
usage: dx clearenv [-h] [--reset]
Clears all environment variables set by dx. More specifically, it removes
local state stored in ~/.dnanexus_config/environment. Does not affect the
environment variables currently set in your shell.
optional arguments:
-h, --help show this help message and exit
--reset Reset dx environment variables to empty values. Use this to
avoid interference between multiple dx sessions when using shell
environment variables.
Navigate and organize your projects and files
usage: dx ls [-h] [--color {off,on,auto}] [--delimiter [DELIMITER]]
[--env-help] [--brief | --verbose] [-a] [-l] [--obj] [--folders]
[--full]
[path]
List folders and/or objects in a folder
positional arguments:
path Folder (possibly in another project) to list the
contents of, default is the current directory in the
current project. Syntax: projectID:/folder/path
optional arguments:
-h, --help show this help message and exit
--color {off,on,auto}
Set when color is used (color=auto is used when stdout
is a TTY)
--delimiter [DELIMITER], --delim [DELIMITER]
Always use exactly one of DELIMITER to separate fields
to be printed; if no delimiter is provided with this
flag, TAB will be used
--env-help Display help message for overriding environment
variables
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
-a, --all show hidden files
-l, --long Alias for "verbose"
--obj show only objects
--folders show only folders
--full show full paths of folders
usage: dx tree [-h] [--color {off,on,auto}] [--env-help] [-a] [-l] [path]
List folders and objects in a tree
positional arguments:
path Folder (possibly in another project) to list the
contents of, default is the current directory in the
current project. Syntax: projectID:/folder/path
optional arguments:
-h, --help show this help message and exit
--color {off,on,auto}
Set when color is used (color=auto is used when stdout
is a TTY)
--env-help Display help message for overriding environment
variables
-a, --all show hidden files
-l, --long use a long listing format
usage: dx pwd [-h] [--env-help]
Print current working directory
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
usage: dx select [-h] [--env-help] [--name NAME]
[--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}] [--public]
[project]
Interactively list and select a project to switch to. By default, only lists
projects for which you have at least CONTRIBUTE permissions. Use --public to
see the list of public projects.
positional arguments:
project Name or ID of a project to switch to; if not provided
a list will be provided for you
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
--name NAME Name of the project (wildcard patterns supported)
--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}
Minimum level of permissions expected
--public Include ONLY public projects (will automatically set
--level to VIEW)
usage: dx cd [-h] [--env-help] [path]
Change the current working directory
positional arguments:
path Folder (possibly in another project) to which to change the
current working directory, default is "/" in the current project
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
usage: dx cp [-h] [--env-help] [-a] source [source ...] destination
Copy objects and/or folders between different projects. Folders will
automatically be copied recursively. To specify which project to use as a
source or destination, prepend the path or ID of the object/folder with the
project ID or name and a colon.
EXAMPLES
The first example copies a file in a project called "FirstProj" to the
current directory of the current project. The second example copies the
object named "reads.fq.gz" in the current directory to the folder
/folder/path in the project with ID "project-B0VK6F6gpqG6z7JGkbqQ000Q",
and finally renaming it to "newname.fq.gz".
$ dx cp FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000q .
$ dx cp reads.fq.gz project-B0VK6F6gpqG6z7JGkbqQ000Q:/folder/path/newname.fq.gz
positional arguments:
source Objects and/or folder names to copy
destination Folder into which to copy the sources or new pathname (if only
one source is provided). Must be in a different
project/container than all source paths.
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-a, --all Apply to all results with the same name without
prompting
usage: dx mv [-h] [--env-help] [-a] source [source ...] destination
Move or rename data objects and/or folders inside a single project. To copy
data between different projects, use 'dx cp' instead.
positional arguments:
source Objects and/or folder names to move
destination Folder into which to move the sources or new pathname (if only
one source is provided). Must be in the same project/container
as all source paths.
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-a, --all Apply to all results with the same name without
prompting
usage: dx mkdir [-h] [--env-help] [-p] path [path ...]
Create a new folder
positional arguments:
path Paths to folders to create
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-p, --parents no error if existing, create parent directories as needed
usage: dx rmdir [-h] [--env-help] path [path ...]
Remove a folder
positional arguments:
path Paths to folders to remove
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
usage: dx rm [-h] [--env-help] [-a] [-r] [-f] path [path ...]
Remove data objects and folders.
positional arguments:
path Paths to remove
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
-r, --recursive Recurse into a directory
-f, --force Force removal of files
usage: dx rmproject [-h] [--env-help] [-y] [-q] project [project ...]
Delete projects and all their associated data
positional arguments:
project Projects to remove
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-y, --yes Do not ask for confirmation
-q, --quiet Do not print purely informational messages
usage: dx archive [-h] [-a] [-q] [--all-copies] [-y] [--no-recurse]
path [path ...]
Requests for the specified set files or for the files in a single specified folder in ONE project to be archived on the platform.
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.
Otherwise, the file will be marked in an archival state denoting that archival has been requested.
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.
To specify which project to use, prepend the path or ID of the file/folder with the project ID or name and a colon.
EXAMPLES:
# archive 3 files in project "FirstProj" with project ID project-B0VK6F6gpqG6z7JGkbqQ000Q
$ dx archive FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000Q FirstProj:/path/to/file1 project-B0VK6F6gpqG6z7JGkbqQ000Q:/file2
# archive 2 files in current project. Specifying file ids saves time by avoiding file name resolution.
$ dx select FirstProj
$ dx archive file-A00000ygpqGK8ZPjbk0Q000Q file-B00000ygpqGK8ZPjbk0Q000Q
# archive all files recursively in project-B0VK6F6gpqG6z7JGkbqQ000Q
$ dx archive project-B0VK6F6gpqG6z7JGkbqQ000Q:/
positional arguments:
path May refer to a single folder or specify up to 1000
files inside a project.
optional arguments:
-h, --help show this help message and exit
-a, --all Apply to all results with the same name without
prompting
-q, --quiet Do not print extra info messages
--all-copies If true, archive all the copies of files in projects
with the same billTo org.
See https://documentation.dnanexus.com/developer/api/d
ata-containers/projects#api-method-project-xxxx-archiv
e for details.
-y, --yes Do not ask for confirmation.
--no-recurse When `path` refers to a single folder, this flag
causes only files in the specified folder and not its
subfolders to be archived. This flag has no impact
when `path` input refers to a collection of files.
Output:
If -q option is not specified, prints "Tagged <count> file(s) for archival"
usage: dx unarchive [-h] [-a] [--rate {Expedited,Standard,Bulk}] [-q] [-y] [--no-recurse] path [path ...]
Requests for a specified set files or for the files in a single specified folder in ONE project to be unarchived on the platform.
The requested copy will eventually be transitioned over to the live state while all other copies will move over to the archival state.
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.
To specify which project to use, prepend the path or ID of the file/folder with the project ID or name and a colon.
EXAMPLES:
# unarchive 3 files in project "FirstProj" with project ID project-B0VK6F6gpqG6z7JGkbqQ000Q
$ dx unarchive FirstProj:file-B0XBQFygpqGK8ZPjbk0Q000Q FirstProj:/path/to/file1 project-B0VK6F6gpqG6z7JGkbqQ000Q:/file2
# unarchive 2 files in current project. Specifying file ids saves time by avoiding file name resolution.
$ dx select FirstProj
$ dx unarchive file-A00000ygpqGK8ZPjbk0Q000Q file-B00000ygpqGK8ZPjbk0Q000Q
# unarchive all files recursively in project-B0VK6F6gpqG6z7JGkbqQ000Q
$ dx unarchive project-B0VK6F6gpqG6z7JGkbqQ000Q:/
positional arguments:
path May refer to a single folder or specify up to 1000 files inside a project.
optional arguments:
-h, --help show this help message and exit
-a, --all Apply to all results with the same name without prompting
--rate {Expedited,Standard,Bulk}
The speed at which all files in this request are unarchived.
- Azure regions: {Expedited, Standard}
- AWS regions: {Expedited, Standard, Bulk}
-q, --quiet Do not print extra info messages
-y, --yes Do not ask for confirmation.
--no-recurse When `path` refers to a single folder, this flag causes only files in the
specified folder and not its subfolders to be unarchived. This flag has no
impact when `path` input refers to a collection of files.
Output:
If -q option is not specified, prints "Tagged <> file(s) for unarchival, totalling <> GB, costing <> "
usage: dx list database files [-h] [--env-help] [--folder FOLDER] [--recurse]
[--csv] [--timeout TIMEOUT]
database
List files associated with a specific database
positional arguments:
database Data object ID or path of the database.
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
--folder FOLDER Name of folder (directory) in which to start searching
for database files. This will typically match the name of
the table whose files are of interest. The default value
is "/" which will start the search at the root folder of
the database.
--recurse Look for files recursively down the directory structure.
Otherwise, by default, only look on one level.
--csv Write output as comma delimited fields, suitable as CSV
format.
--timeout TIMEOUT Number of seconds to wait before aborting the request. If
omitted, default timeout is 120 seconds.
View, download, and upload data
usage: dx describe [-h] [--json] [--color {off,on,auto}]
[--delimiter [DELIMITER]] [--env-help] [--details]
[--verbose] [--name] [--multi]
path
Describe a DNAnexus entity. Use this command to describe data objects by name
or ID, jobs, apps, users, organizations, etc. If using the "--json" flag, it
will thrown an error if more than one match is found (but if you would like a
JSON array of the describe hashes of all matches, then provide the "--multi"
flag). Otherwise, it will always display all results it finds.
NOTES:
- The project found in the path is used as a HINT when you are using an object
ID; you may still get a result if you have access to a copy of the object in
some other project, but if it exists in the specified project, its description
will be returned.
- When describing apps or applets, options marked as advanced inputs will be
hidden unless --verbose is provided
positional arguments:
path Object ID or path to an object (possibly in another
project) to describe.
optional arguments:
-h, --help show this help message and exit
--json Display return value in JSON
--color {off,on,auto}
Set when color is used (color=auto is used when stdout
is a TTY)
--delimiter [DELIMITER], --delim [DELIMITER]
Always use exactly one of DELIMITER to separate fields
to be printed; if no delimiter is provided with this
flag, TAB will be used
--env-help Display help message for overriding environment
variables
--details Include details of data objects
--verbose Include all possible metadata
--name Only print the matching names, one per line
--multi If the flag --json is also provided, then returns a
JSON array of describe hashes of all matching results
usage: dx upload [-h] [--visibility {hidden,visible}] [--property KEY=VALUE]
[--type TYPE] [--tag TAG] [--details DETAILS] [-p]
[--brief | --verbose] [--env-help] [--path [PATH]] [-r]
[--wait] [--no-progress] [--buffer-size WRITE_BUFFER_SIZE]
[--singlethread]
filename [filename ...]
Upload local file(s) or directory. If "-" is provided, stdin will be used
instead. By default, the filename will be used as its new name. If
--path/--destination is provided with a path ending in a slash, the filename
will be used, and the folder path will be used as a destination. If it does
not end in a slash, then it will be used as the final name.
positional arguments:
filename Local file or directory to upload ("-" indicates stdin
input); provide multiple times to upload multiple
files or directories
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--env-help Display help message for overriding environment
variables
--path [PATH], --destination [PATH]
DNAnexus path to upload file(s) to (default uses
current project and folder if not provided)
-r, --recursive Upload directories recursively
--wait Wait until the file has finished closing
--no-progress Do not show a progress bar
--buffer-size WRITE_BUFFER_SIZE
Set the write buffer size (in bytes)
--singlethread Enable singlethreaded uploading
metadata arguments:
--visibility {hidden,visible}
Whether the object is hidden or not
--property KEY=VALUE Key-value pair to add as a property; repeat as
necessary, e.g. "--property key1=val1 --property
key2=val2"
--type TYPE Type of the data object; repeat as necessary, e.g. "--
type type1 --type type2"
--tag TAG Tag of the data object; repeat as necessary, e.g. "--
tag tag1 --tag tag2"
--details DETAILS JSON to store as details
-p, --parents Create any parent folders necessary
usage: dx download [-h] [--env-help] [-o OUTPUT] [-f] [-r] [-a]
[--no-progress] [--lightweight] [--unicode]
path [path ...]
Download the contents of a file object or multiple objects. Use "-o -" to
direct the output to stdout.
positional arguments:
path Data object ID or name, or folder to download
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-o OUTPUT, --output OUTPUT
Local filename or directory to be used ("-" indicates
stdout output); if not supplied or a directory is
given, the object's name on the platform will be used,
along with any applicable extensions
-f, --overwrite Resume an interupted download if the local and remote
file signatures match. If the signatures do not match
the local file will be overwritten.
-r, --recursive Download folders recursively
-a, --all If multiple objects match the input, download all of
them
--no-progress Do not show a progress bar
--lightweight Skip some validation steps to make fewer API calls
--unicode Display the characters as text/unicode when writing to
stdout
usage: dx make_download_url [-h] [--duration DURATION] [--filename FILENAME]
path
Creates a pre-authenticated link that can be used to download a file without
logging in.
positional arguments:
path Data object ID or name to access
optional arguments:
-h, --help show this help message and exit
--duration DURATION Time for which the URL will remain valid (in seconds,
or use suffix s, m, h, d, w, M, y). Default: 1 day
--filename FILENAME Name that the server will instruct the client to save
the file as (default is the filename)
usage: dx cat [-h] [--env-help] [--unicode] path [path ...]
positional arguments:
path File ID or name(s) to print to stdout
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
--unicode Display the characters as text/unicode when writing to stdout
usage: dx head [-h] [--color {off,on,auto}] [--env-help] [-n N] path
Print the first part of a file. By default, prints the first 10 lines.
positional arguments:
path File ID or name to access
optional arguments:
-h, --help show this help message and exit
--color {off,on,auto}
Set when color is used (color=auto is used when stdout
is a TTY)
--env-help Display help message for overriding environment
variables
-n N, --lines N Print the first N lines (default 10)
usage: dx new [-h] class ...
Use this command with one of the available subcommands (classes) to create a
new project or data object from scratch. Not all data types are supported. See
'dx upload' for files and 'dx build' for applets.
positional arguments:
class
user Create a new user account
org Create new non-billable org
project Create a new project
record Create a new record
workflow Create a new workflow
optional arguments:
-h, --help show this help message and exit
usage: dx new project [-h] [--brief | --verbose] [--env-help]
[--region REGION] [-s] [--bill-to BILL_TO] [--phi]
[--database-ui-view-only]
[name]
Create a new project
positional arguments:
name Name of the new project
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--env-help Display help message for overriding environment
variables
--region REGION Region affinity of the new project
-s, --select Select the new project as current after creating
--bill-to BILL_TO ID of the user or org to which the project will be
billed. The default value is the billTo of the
requesting user.
--phi Add PHI protection to project
--database-ui-view-only
If set to true, viewers of the project will not be
able to access database data directly
usage: dx new record [-h] [--visibility {hidden,visible}]
[--property KEY=VALUE] [--type TYPE] [--tag TAG]
[--details DETAILS] [-p] [--brief | --verbose]
[--env-help] [--init INIT] [--close]
[path]
Create a new record
positional arguments:
path DNAnexus path for the new data object (default uses
current project and folder if not provided)
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--env-help Display help message for overriding environment
variables
--init INIT Path to record from which to initialize all metadata
--close Close the record immediately after creating it
metadata arguments:
--visibility {hidden,visible}
Whether the object is hidden or not
--property KEY=VALUE Key-value pair to add as a property; repeat as
necessary,
e.g. "--property key1=val1 --property key2=val2"
--type TYPE Type of the data object; repeat as necessary,
e.g. "--type type1 --type type2"
--tag TAG Tag of the data object; repeat as necessary,
e.g. "--tag tag1 --tag tag2"
--details DETAILS JSON to store as details
-p, --parents Create any parent folders necessary
usage: dx new workflow [-h] [--visibility {hidden,visible}]
[--property KEY=VALUE] [--type TYPE] [--tag TAG]
[--details DETAILS] [-p] [--brief | --verbose]
[--env-help] [--title TITLE] [--summary SUMMARY]
[--description DESCRIPTION]
[--output-folder OUTPUT_FOLDER] [--init INIT]
[path]
Create a new workflow
positional arguments:
path DNAnexus path for the new data object (default uses
current project and folder if not provided)
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--env-help Display help message for overriding environment
variables
--title TITLE Workflow title
--summary SUMMARY Workflow summary
--description DESCRIPTION
Workflow description
--output-folder OUTPUT_FOLDER
Default output folder for the workflow
--init INIT Path to workflow or an analysis ID from which to
initialize all metadata
metadata arguments:
--visibility {hidden,visible}
Whether the object is hidden or not
--property KEY=VALUE Key-value pair to add as a property; repeat as
necessary,
e.g. "--property key1=val1 --property key2=val2"
--type TYPE Type of the data object; repeat as necessary,
e.g. "--type type1 --type type2"
--tag TAG Tag of the data object; repeat as necessary,
e.g. "--tag tag1 --tag tag2"
--details DETAILS JSON to store as details
-p, --parents Create any parent folders necessary
usage: dx close [-h] [--env-help] [-a] [--wait] path [path ...]
Close a remote data object or set of objects.
positional arguments:
path Path to a data object to close
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
--wait Wait for the object(s) to close
usage: dx wait [-h] [--env-help] [--from-file] path [path ...]
Polls the state of specified data object(s) or job(s) until they are all in
the desired state. Waits until the "closed" state for a data object, and for
any terminal state for a job ("terminated", "failed", or "done"). Exits with a
non-zero code if a job reaches a terminal state that is not "done". Can also
provide a local file containing a list of data object(s) or job(s), one per
line; the file will be read if "--from-file" argument is added.
positional arguments:
path Path to a data object, job ID, or file with IDs to wait for
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
--from-file Read the list of objects to wait for from the file provided in
path
usage: dx get [-h] [--env-help] [-o OUTPUT] [--filename FILENAME]
[--allow-all-files] [--recurse] [--no-ext] [--omit-resources]
[-f]
path
Download the contents of some types of data (records, apps, applets,
workflows, files, and databases). Downloading an app, applet or a workflow
will attempt to reconstruct a source directory that can be used to rebuild it
with "dx build". Use "-o -" to direct the output to stdout.
positional arguments:
path Data object ID or name to access
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-o OUTPUT, --output OUTPUT
local file path where the data is to be saved ("-"
indicates stdout output for objects of class file and
record). If not supplied, the object's name on the
platform will be used, along with any applicable
extensions. For app(let) and workflow objects, if
OUTPUT does not exist, the object's source directory
will be created there; if OUTPUT is an existing
directory, a new directory with the object's name will
be created inside it.
--filename FILENAME When downloading from a database, name of the file or
folder to be downloaded. If omitted, all files in the
database will be downloaded, so use caution and
include the --allow-all-files argument.
--allow-all-files When downloading from a database, this allows all
files in a database to be downloaded when --filename
argument is omitted.
--recurse When downloading from a database, look for files
recursively down the directory structure. Otherwise,
by default, only look on one level.
--no-ext If -o is not provided, do not add an extension to the
filename
--omit-resources When downloading an app(let), omit fetching the
resources associated with the app(let).
-f, --overwrite Overwrite the local file if necessary
usage: dx find data [-h] [--brief | --verbose] [--json]
[--color {off,on,auto}] [--delimiter [DELIMITER]]
[--env-help] [--property KEY[=VALUE]] [--tag TAG]
[--class {record,file,applet,workflow,database}]
[--state {open,closing,closed,any}]
[--visibility {hidden,visible,either}] [--name NAME]
[--type TYPE] [--link LINK] [--all-projects]
[--path PROJECT:FOLDER] [--norecurse]
[--created-after CREATED_AFTER]
[--created-before CREATED_BEFORE] [--mod-after MOD_AFTER]
[--mod-before MOD_BEFORE] [--region REGION]
Finds data objects subject to the given search parameters. By default,
restricts the search to the current project if set. To search over all
projects (excluding public projects), use --all-projects (overrides --path and
--norecurse).
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--json Display return value in JSON
--color {off,on,auto}
Set when color is used (color=auto is used when stdout
is a TTY)
--delimiter [DELIMITER], --delim [DELIMITER]
Always use exactly one of DELIMITER to separate fields
to be printed; if no delimiter is provided with this
flag, TAB will be used
--env-help Display help message for overriding environment
variables
--property KEY[=VALUE]
Key-value pair of a property or simply a property key;
if only a key is provided, matches a result that has
the key with any value; repeat as necessary, e.g. "--
property key1=val1 --property key2"
--tag TAG Tag to match; repeat as necessary, e.g. "--tag tag1
--tag tag2" will require both tags
--class {record,file,applet,workflow,database}
Data object class
--state {open,closing,closed,any}
State of the object
--visibility {hidden,visible,either}
Whether the object is hidden or not
--name NAME Name of the object
--type TYPE Type of the data object
--link LINK Object ID that the data object links to
--all-projects, --allprojects
Extend search to all projects (excluding public
projects)
--path PROJECT:FOLDER
Project and/or folder in which to restrict the results
--norecurse Do not recurse into subfolders
--created-after CREATED_AFTER
Date (e.g. 2012-01-01) or integer timestamp after
which the object was created (negative number means ms
in the past, or use suffix s, m, h, d, w, M, y)
Negative input example "--created-after=-2d"
--created-before CREATED_BEFORE
Date (e.g. 2012-01-01) or integer timestamp before
which the object was created (negative number means ms
in the past, or use suffix s, m, h, d, w, M, y)
Negative input example "--created-before=-2d"
--mod-after MOD_AFTER
Date (e.g. 2012-01-01) or integer timestamp after
which the object was last modified (negative number
means ms in the past, or use suffix s, m, h, d, w, M,
y) Negative input example "--mod-after=-2d"
--mod-before MOD_BEFORE
Date (e.g. 2012-01-01) or integer timestamp before
which the object was last modified (negative number
means ms in the past, or use suffix s, m, h, d, w, M,
y) Negative input example "--mod-before=-2d"
--region REGION Restrict the search to the provided region
usage: dx find projects [-h] [--brief | --verbose] [--json]
[--delimiter [DELIMITER]] [--env-help]
[--property KEY[=VALUE]] [--tag TAG]
[--phi {true,false}] [--name NAME]
[--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}]
[--public] [--created-after CREATED_AFTER]
[--created-before CREATED_BEFORE] [--region REGION]
Finds projects subject to the given search parameters. Use the --public flag
to list all public projects.
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--json Display return value in JSON
--delimiter [DELIMITER], --delim [DELIMITER]
Always use exactly one of DELIMITER to separate fields
to be printed; if no delimiter is provided with this
flag, TAB will be used
--env-help Display help message for overriding environment
variables
--property KEY[=VALUE]
Key-value pair of a property or simply a property key;
if only a key is provided, matches a result that has
the key with any value; repeat as necessary, e.g. "--
property key1=val1 --property key2"
--tag TAG Tag to match; repeat as necessary, e.g. "--tag tag1
--tag tag2" will require both tags
--phi {true,false} If set to true, only projects that contain PHI data
will be retrieved. If set to false, only projects that
do not contain PHI data will be retrieved.
--name NAME Name of the project
--level {VIEW,UPLOAD,CONTRIBUTE,ADMINISTER}
Minimum level of permissions expected
--public Include ONLY public projects (will automatically set
--level to VIEW)
--created-after CREATED_AFTER
Date (e.g. 2012-01-01) or integer timestamp after
which the project was created (negative number means
ms in the past, or use suffix s, m, h, d, w, M, y)
Negative input example "--created-after=-2d"
--created-before CREATED_BEFORE
Date (e.g. 2012-01-01) or integer timestamp after
which the project was created (negative number means
ms in the past, or use suffix s, m, h, d, w, M, y)
Negative input example "--created-before=-2d"
--region REGION Restrict the search to the provided region
usage: dx update project [-h] [--brief | --verbose] [--env-help] [--name NAME]
[--summary SUMMARY] [--description DESCRIPTION]
[--protected {true,false}]
[--restricted {true,false}]
[--download-restricted {true,false}]
[--containsPHI {true}]
[--database-ui-view-only {true,false}]
[--bill-to BILL_TO]
[--allowed-executables ALLOWED_EXECUTABLES
[ALLOWED_EXECUTABLES ...]
| --unset-allowed-executables]
project_id
positional arguments:
project_id Project ID or project name
optional arguments:
-h, --help show this help message and exit
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--env-help Display help message for overriding environment
variables
--name NAME New project name
--summary SUMMARY Project summary
--description DESCRIPTION
Project description
--protected {true,false}
Whether the project should be PROTECTED
--restricted {true,false}
Whether the project should be RESTRICTED
--download-restricted {true,false}
Whether the project should be DOWNLOAD RESTRICTED
--containsPHI {true} Flag to tell if project contains PHI
--database-ui-view-only {true,false}
Whether the viewers on the project can access the
database data directly
--bill-to BILL_TO Update the user or org ID of the billing account
--allowed-executables ALLOWED_EXECUTABLES [ALLOWED_EXECUTABLES ...]
Executable ID(s) this project is allowed to run. This
operation overrides any existing list of executables.
--unset-allowed-executables
Removes any restriction to run executables as set by
--allowed-executables
usage: dx extract_dataset [-h] [-ddd] [--fields FIELDS [FIELDS ...]] [--sql]
[--delim [DELIM]] [-o OUTPUT]
path
(Preview Feature) Retrieves the data or generates SQL to retrieve the data from a dataset or
cohort for a set of entity.fields. Additionally, the dataset's dictionary can
be extracted independently or in conjunction with data. Note: A separate version of pandas may be required to install when using this functionality.
positional arguments:
path v3.0 Dataset or Cohort object ID (project-id:record-id
where "record-id" indicates the record ID in the
currently selected project) or name
optional arguments:
-h, --help show this help message and exit
-ddd, --dump-dataset-dictionary
If provided, the three dictionary files,
<record_name>.data_dictionary.csv,
<record_name>.entity_dictionary.csv, and
<record_name>.codings.csv will be generated. Files
will be comma delimited and written to the local
working directory, unless otherwise specified using
--delimiter and --output arguments. If any of the
three dictionary files does not contain data (i.e. the
dictionary is empty), then that particular file will
not be created.
--fields FIELDS [FIELDS ...]
A comma-separated string where each value is the
phenotypic entity name and field name, separated by a
dot. For example: "<entity_name>.<field_name>,<entity
_name>.<field_name>". If multiple entities are
provided, field values will be automatically inner
joined. If only the --fields argument is provided,
data will be retrieved and returned. If both --fields
and --sql arguments are provided, a SQL statement to
retrieve the specified field data will be
automatically generated and returned.
--sql If provided, a SQL statement (string) will be returned
to query the set of entity.fields, instead of
returning stored values from the set of entity.fields
--delim [DELIM], --delimiter [DELIM]
Always use exactly one of DELIMITER to separate fields
to be printed; if no delimiter is provided with this
flag, COMMA will be used
-o OUTPUT, --output OUTPUT
Local filename or directory to be used ("-" indicates
stdout output). If not supplied, output will create a
file with a default name in the current folder
View and modify metadata for projects and data objects.
See also dx describe and dx close.
usage: dx set_details [-h] [--env-help] [-a] [-f DETAILS_FILE] path [details]
Set the JSON details of a data object.
positional arguments:
path ID or path to data object to modify
details JSON to store as details
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-a, --all Apply to all results with the same name without
prompting
-f DETAILS_FILE, --details-file DETAILS_FILE
Path to local file containing JSON to store as details
usage: dx get_details [-h] [--env-help] path
Get the JSON details of a data object.
positional arguments:
path ID or path to data object to get details for
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
usage: dx set_visibility [-h] [--env-help] [-a] path {hidden,visible}
Set visibility on a data object.
positional arguments:
path ID or path to data object to modify
{hidden,visible} Visibility that the object should have
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx add_types [-h] [--env-help] [-a] path type [type ...]
Add types to a data object. See
https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types
for a list of DNAnexus types.
positional arguments:
path ID or path to data object to modify
type Types to add
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx remove_types [-h] [--env-help] [-a] path type [type ...]
Remove types from a data object. See
https://documentation.dnanexus.com/developer/api/data-object-lifecycle/types
for a list of DNAnexus types.
positional arguments:
path ID or path to data object to modify
type Types to remove
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx tag [-h] [--env-help] [-a] path tag [tag ...]
Tag a project, data object, or execution. Note that a project context must be
either set or specified for data object IDs or paths.
positional arguments:
path ID or path to project, data object, or execution to modify
tag Tags to add
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx untag [-h] [--env-help] [-a] path tag [tag ...]
Untag a project, data object, or execution. Note that a project context must
be either set or specified for data object IDs or paths.
positional arguments:
path ID or path to project, data object, or execution to modify
tag Tags to remove
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx rename [-h] [--env-help] [-a] path name
Rename a project or data object. To rename folders, use 'dx mv' instead. Note
that a project context must be either set or specified to rename a data
object. To specify a project or a project context, append a colon character
":" after the project ID or name.
positional arguments:
path Path to project or data object to rename
name New name
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
usage: dx set_properties [-h] [--env-help] [-a]
path propertyname=value [propertyname=value ...]
Set properties of a project, data object, or execution. Note that a project
context must be either set or specified for data object IDs or paths.
positional arguments:
path ID or path to project, data object, or execution to
modify
propertyname=value Key-value pairs of property names and their new values
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
-a, --all Apply to all results with the same name without
prompting
usage: dx unset_properties [-h] [--env-help] [-a]
path propertyname [propertyname ...]
Unset properties of a project, data object, or execution. Note that a project
context must be either set or specified for data object IDs or paths.
positional arguments:
path ID or path to project, data object, or execution to modify
propertyname Property names to unset
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment variables
-a, --all Apply to all results with the same name without prompting
Manage and run your apps, applets, and workflows.
usage: dx build [-h] [--env-help] [--brief | --verbose] [--ensure-upload]
[--force-symlinks] [--app] [--workflow] [--globalworkflow]
[-d DESTINATION] [--dry-run] [--publish] [--from _FROM]
[--remote] [--no-watch] [-f] [-a] [-v VERSION]
[-b USER_OR_ORG] [--no-check-syntax]
[--no-version-autonumbering] [--no-update]
[--no-dx-toolkit-autodep] [--no-parallel-build]
[--no-temp-build-project] [-y] [--extra-args EXTRA_ARGS]
[--run ...] [--region REGION] [--keep-open]
[src_dir]
Build an applet, app, or workflow object from a local source directory or an
app from an existing applet in the platform. You can use dx-app-wizard to
generate a skeleton directory of an app/applet with the necessary files.
positional arguments:
src_dir Source directory that contains dxapp.json or
dxworkflow.json. (default: current directory)
optional arguments:
-h, --help show this help message and exit
--env-help Display help message for overriding environment
variables
--brief Display a brief version of the return value; for most
commands, prints a DNAnexus ID per line
--verbose If available, displays extra verbose output
--ensure-upload If specified, will bypass computing checksum of
resources directory and upload it unconditionally; by
default, will compute checksum and upload only if it
differs from a previously uploaded resources bundle.
--force-symlinks If specified, will not attempt to dereference symbolic
links pointing outside of the resource directory. By
default, any symlinks within the resource directory
are kept as links while links to files outside the
resource directory are dereferenced (note that links
to directories outside of the resource directory will
cause an error).
--app, --create-app Create an app.
--workflow, --create-workflow
Create a workflow.
--globalworkflow, --create-globalworkflow
Create a global workflow.
--dry-run, -n Do not create an app(let): only perform local checks
and compilation steps, and show the spec of the
app(let) that would have been created.
--remote Build the app remotely by uploading the source
directory to the DNAnexus Platform and building it
there. This option is useful if you would otherwise
need to cross-compile the app(let) to target the
Execution Environment.
--no-watch Don't watch the real-time logs of the remote builder.
(This option only applicable if --remote was
specified).
-v VERSION, --version VERSION
Override the version number supplied in the manifest.
This option needs to be specified when using --from
option.
--no-check-syntax Warn but do not fail when syntax problems are found
(default is to fail on such errors)
--no-dx-toolkit-autodep
Do not auto-insert the dx-toolkit dependency (default
is to add it if it would otherwise be absent from the
runSpec)
--no-parallel-build Build with make instead of make -jN.
--extra-args EXTRA_ARGS
Arguments (in JSON format) to pass to the /applet/new
API method, overriding all other settings
--run ... Run the app or applet after building it (options
following this are passed to dx run; run at high
priority by default)
--keep-open Do not close workflow after building it. Cannot be
used when building apps, applets or global workflows.
options for creating apps or globalworkflows:
(Only valid when --app/--create-app/--globalworkflow/--create-
globalworkflow is specified)
--publish Publish the resulting app/globalworkflow and make it
the default.
--from _FROM ID or path of the source applet/workflow to create an
app/globalworkflow from. Source directory src_dir
cannot be given when using this option
-b USER_OR_ORG, --bill-to USER_OR_ORG
Entity (of the form user-NAME or org-ORGNAME) to bill
for the app/globalworkflow.
--no-version-autonumbering
Only attempt to create the version number supplied in
the manifest (that is, do not try to create an
autonumbered version such as 1.2.3+git.ab1b1c1d if
1.2.3 already exists and is published).
--no-update Never update an existing unpublished
app/globalworkflow in place.
--no-temp-build-project
When building an app in a single region, build its
applet in the current project instead of a temporary
project.
-y, --yes Do not ask for confirmation for potentially dangerous
operations
--region REGION Enable the app/globalworkflow in this region. This
flag can be specified multiple times to enable the
app/globalworkflow in multiple regions. If --region is
not specified, then the enabled region(s) will be
determined by 'regionalOptions' in dxapp.json, or the
project context.
options for creating applets or workflows:
(Only valid when --app/--create-app/--globalworkflow/--create-
globalworkflow is NOT specified)
-d DESTINATION, --destination DESTINATION
Specifies the destination project, destination folder,
and/or name for the applet, in the form
[PROJECT_NAME_OR_ID:][/[FOLDER/][NAME]]. Overrides the
project, folder, and name fields of the dxapp.json or
dxworkflow.json, if they were supplied.
-f, --overwrite Remove existing applet(s) of the same name in the
destination folder. This option is not yet supported
for workflows.
-a, --archive Archive existing applet(s) of the same name in the
destination folder. This option is not yet supported
for workflows.