Find and use commands

Because dct-toolkit covers a wide range of functions supported by DCT, finding the right command can be difficult. Use dct-toolkit -h or dct-toolkit --help to display the list of currently supported function commands. It is a good idea to review this list the first time you use the toolkit and again after a DCT upgrade. The help output groups function commands by category. Although the order differs, you can compare the supported functions with the DCT Swagger UI at https://{DCT_IP_ADDRESS}/dct/api.

$ dct-toolkit --version
                dct-toolkit
                1.5.0
                OS: Linux 3.10.0-1160.108.1.el7.x86_64 amd64

                $ dct-toolkit -h
                Usage: dct-toolkit [-hV] [COMMAND]
                -h, --help      Show this help message and exit.
                -V, --version   Print version information and exit.

                Commands:
                Accounts:
                get_accounts
                create_account
                api_key_reset
                ...
                Bookmarks:
                get_bookmarks
                create_bookmark
                search_bookmarks
                ...
                VDBs:
                get_vdbs
                search_vdbs
                get_vdb_by_id
            ...

Keep in mind that the dct-toolkit -h or --help command displays all functions supported by dct-toolkit, regardless of the role or permission settings of the DCT user associated with the API key configured through create_config. As a result, the help output may include functions that the current user does not have permission to run. Actual access is still controlled through the normal RBAC mechanisms.

About function command help

Use dct-toolkit <function_command> -h or dct-toolkit <function_command> --help to view the options and arguments for a specific function command.

$ dct-toolkit refresh_vdb_from_bookmark -h
                Usage: dct-toolkit refresh_vdb_from_bookmark [-hVw] vdb_id=<vdbId> [-cs] [-jh]
                ([bookmark_id=string] | [--body=PARAM]) [-jp=<jsonPath> | -ex=<expand>]
                [-A | -c=<columnsList>[,<columnsList>...] | -js]

                -h, --help                 Show this help message and exit.
                -V, --version              Print version information and exit.
                vdbId, vdb_id=<vdbId>  The ID of the VDB.
                bookmark_id=string     The ID of the bookmark from which to execute the operation.
                --body=PARAM           The parameters to refresh a VDB.
                -w, --[no-]wait            Wait for asynchronous job completion.
                -jp, --jsonpath=<jsonPath>
                Extract a specific object from the successful response.
                -ex, --expand=<expand> Render a nested array or object from the response.
                -A, --[no-]all-columns     Print all properties while rendering the response in table format.
                -c, --columns=<columnsList>[,<columnsList>...]
                Select specific properties while rendering the response in table format.
                -js, --[no-]json       Output the response in JSON format.
                -cs, --[no-]csv        Output the response in CSV format.
            -jh, --[no-]jsonhelp   Print help that includes the request and response JSON structures.

This output follows the general command help format. Options and arguments that are not enclosed in square brackets are required. In the refresh_vdb_from_bookmark example, vdb_id=<vdbId> is required. The bookmark_id value is also needed for the operation, but it can be supplied either directly as bookmark_id=string or through --body=PARAM.

For the value supplied with --body, use the same JSON data structure shown in the Request body of the REST API. For example, refresh_vdb_from_bookmark can be run with --body='{ "bookmark_id": "xxxx" }'.

For function commands that only display information, such as the get_xxxx series that map to GET endpoints in the REST API, the --body=PARAM option cannot be used.

$ dct-toolkit get_vdbs -h
                Usage: dct-toolkit get_vdbs [-hVw] [-cs] [-jh] [cursor=<cursor>] [limit=<limit>]
                [permission=<permission>] [sort=<sort>] [-jp=<jsonPath> | -ex=<expand>]
                [-A | -c=<columnsList>[,<columnsList>...] | -js]

            -A, --[no-]all-columns     Print all properties while rendering the response in table format.

For commands that use a request body, dct-toolkit provides -body, which can be used to specify a JSON body (instead of using individual options).

dct-toolkit token_info --body=<JSON body to POST to DCT>

Help regarding the exact structure of JSON request and response body can be requested for all of the commands with the following command:

-jh/--jsonhelp
            dct-toolkit token_info -jh

Searching for commands by keyword

If you are unsure of a command's exact name, pipe the help output through grep to filter by keyword:

$ dct-toolkit -h | grep <keyword>

You can also grep within a specific command's help output to find a particular argument:

$ dct-toolkit <command> -h | grep <argument>

Tab completion is also available to speed up command entry. See Auto-completion support for setup instructions.

Alternatively, entering an unknown or incomplete command returns a list of suggestions. For example, entering dct-toolkit search returns suggestions such as search_vdbs, search_dsources, and other commands matching that prefix.

search_* vs get_* commands

dct-toolkit provides two categories of commands for retrieving objects: search_* commands and get_* commands. Both return similar data but are designed for different purposes.

get_* commands

get_* commands are tailored for common, human-friendly retrieval scenarios. They accept either a name or an ID in a single argument field, return results in a readable default format, and cover the most frequently needed query patterns. Examples include get_vdbs, get_vdb_by_id, and get_dsource_snapshots.

Use get_* commands for interactive exploration and one-off queries where readability is the priority.

search_* commands

search_* commands are designed for automation. They support a broader range of query permutations and more granular filtering options than their get_* equivalents. Anything a get_* command can retrieve can also be retrieved with the equivalent search_* command, but not always the other way around.

Note that search_* commands treat name and ID as separate fields. You must specify explicitly whether you are filtering by name or by ID. This differs from get_* commands, where a single argument accepts either value.

For scripts and automated workflows, search_* commands are generally the better choice. Their consistent structure and expanded filtering support make them more predictable across a wider range of use cases.

Output format

All list commands support three output formats. Use the appropriate flag to control what is returned:

JSON and CSV output include all response properties. Table output shows a default subset; use --columns to specify which fields to display, or --all-columns / -A to print everything.

Pagination

dct-toolkit returns a maximum of 1000 items per response. If a result set exceeds this limit, use cursor-based iteration: take the last value from the current response and pass it back into the command as the cursor argument to retrieve the next page of results.

CLI and API parity

dct-toolkit commands map directly to DCT API calls. Every new or updated API endpoint corresponds to a new or updated CLI command. If you are troubleshooting a command or want to inspect request and response structures visually, the DCT Swagger UI is a useful companion — confirm the behavior in Swagger, then return to the CLI to execute it.

dct-toolkit does not need to be upgraded for every DCT release. It reads the API specification from the configured DCT instance and dynamically generates the available commands and options, though CLI-specific fixes and changes may still require upgrading the toolkit.