Command reference

Common parameters and options

Some parameters and options are shared by multiple dcc subcommands.

Arguments

Arguments are positional, and are usually required by commands that support them.

DCC_NUMBER

A DCC number.

Options and flags

Options and flags are optional parameters that change the behaviour of a command. Options require a value of some sort, whereas flags don’t.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

--ignore-version

Attempt to fetch the latest version of the document specified in DCC_NUMBER from the local archive regardless of the version specified. If no local version exists, the version of the document given in DCC_NUMBER (or, if no version is specified, the latest version) will still be fetched from the DCC.

--depth

Recursively fetch referencing documents up to this many levels.

Fetch related documents when --depth is nonzero.

--fetch-referencing, --no-fetch-referencing

Fetch referencing documents when --depth is nonzero.

-f, --force

Force retrieval of a record or file from the remote DCC host even if it exists in the local archive. The locally archived record or file is overwritten with the retrieved version.

--skip-category

Skip retrieval of a particular document type, such as M (“Management or Policy”). This can be specified multiple times, for different document types.

--files

In addition to fetching the record, fetch its attached files too.

--max-file-size

Maximum file size to download, in MB. If larger, the file is skipped. Note: this behaviour relies on the DCC host providing a Content-Length header. If it does not, the file is downloaded regardless of its real size.

--progress, --no-progress

Show or hide a download progress bar. For small files the progress bar may not be shown. By default this is enabled.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

--public

Only attempt to retrieve public DCC records. This should avoid triggering an authentication check.

dcc archive

Archive remote DCC records locally.

Each specified NUMBER should be a DCC record designation with optional version such as ‘D040105’ or ‘D040105-v1’.

If a DCC number contains a version and is present in the local archive, it is skipped unless --force is specified. If the DCC number does not contain a version, a version exists in the local archive, and --ignore-version is specified, its archival is skipped as well. In all other cases, the latest record is fetched from the remote host.

NUMBER

A DCC number to archive (can be specified multiple times).

--from-file

Archive records specified in file.

--depth

Recursively fetch referencing documents up to this many levels.

Fetch related documents when --depth is nonzero.

--fetch-referencing, --no-fetch-referencing

Fetch referencing documents when --depth is nonzero.

--files

In addition to fetching the record, fetch its attached files too.

-i, --interactive

Enable interactive mode, which prompts for confirmation before downloading files. This flag implies --files, and --max-file-size is ignored.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

--ignore-version

Attempt to fetch the latest version of each DCC number from the local archive regardless of the version specified. If no local version exists, the version of the document given in the DCC number (or, if no version is specified, the latest version) will still be fetched from the DCC.

--max-file-size

Maximum file size to download, in MB. If larger, the file is skipped. Note: this behaviour relies on the DCC host providing a Content-Length header. If it does not, the file is downloaded regardless of its real size.

--skip-category

Skip retrieval of a particular document type, such as M (“Management or Policy”). This can be specified multiple times, for different document types.

--progress, --no-progress

Show or hide a download progress bar. For small files the progress bar may not be shown. By default this is enabled.

-f, --force

Force retrieval of a record or file from the remote DCC host even if it exists in the local archive. The locally archived record or file is overwritten with the retrieved version.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

--public

Only attempt to retrieve public DCC records. This should avoid triggering an authentication check.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc convert

Extract DCC numbers from a target file or URL and write to DST.

Any text in the document at SRC that appears to be a DCC number is written to DST.

SRC can be a path to a local file (or stdin) or a web address.

SRC

The file or URL to scrape for DCC numbers. Can be a path to a local file or a web address.

DST

The file to write extracted DCC numbers to.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc list

List records in the local archive.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc open

Open remote DCC record page in the default browser.

DCC_NUMBER should be a DCC record designation with optional version such as D040105 or D040105-v1.

DCC_NUMBER

The number for the DCC record to archive.

--xml

Open URL for XML document.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

--public

Only attempt to retrieve public DCC records. This should avoid triggering an authentication check.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc open-file

Open file attached to DCC record using operating system.

DCC_NUMBER should be a DCC record designation with optional version such as D040105 or D040105-v1.

FILE_NUMBER should be an integer starting from 1 representing the position of the file as listed by dcc view DCC_NUMBER. The file will be opened with the default application for its type as determined by the operating system. If --locate is specified, the file is instead selected in the default file browser.

If DCC_NUMBER contains a version and is present in the local archive, it is used unless --force is specified. If DCC_NUMBER does not contain a version, a version exists in the local archive, and --ignore-version is specified, the latest local version is used. In all other cases, the latest record is fetched from the remote host.

DCC_NUMBER

The number for the DCC record to archive.

FILE_NUMBER

The file number to open.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

--ignore-version

Attempt to fetch the latest version of the document specified in DCC_NUMBER from the local archive regardless of the version specified. If no local version exists, the version of the document given in DCC_NUMBER (or, if no version is specified, the latest version) will still be fetched from the DCC.

--max-file-size

Maximum file size to download, in MB. If larger, the file is skipped. Note: this behaviour relies on the DCC host providing a Content-Length header. If it does not, the file is downloaded regardless of its real size.

--locate

Instead of opening the file, open a file browser with the downloaded file selected.

--progress, --no-progress

Show or hide a download progress bar. For small files the progress bar may not be shown. By default this is enabled.

-f, --force

Force retrieval of a record or file from the remote DCC host even if it exists in the local archive. The locally archived record or file is overwritten with the retrieved version.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

--public

Only attempt to retrieve public DCC records. This should avoid triggering an authentication check.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc update

Update remote DCC record metadata.

DCC_NUMBER should be a DCC record designation with optional version such as D040105 or D040105-v1.

Any metadata specified for a particular field overwrites all of the existing record metadata for that field.

DCC_NUMBER

The number for the DCC record to update.

--title

The new title.

--abstract

The new abstract.

--keyword

A keyword (can be specified multiple times).

--note

The new note.

A new related document number (can be specified multiple times).

--author

An author in the form “Albert Einstein” (can be specified multiple times).

--confirm, --no-confirm

Prompt (--confirm) or don’t prompt (--no-confirm) for confirmation before actually submitting the update to the remote DCC host.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

-f, --force

Force retrieval of a record or file from the remote DCC host even if it exists in the local archive. The locally archived record or file is overwritten with the retrieved version.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

dcc view

View DCC record metadata.

DCC_NUMBER should be a DCC record designation with optional version such as D040105 or D040105-v1.

If DCC_NUMBER contains a version and is present in the local archive, it is used unless --force is specified. If DCC_NUMBER does not contain a version, a version exists in the local archive, and --ignore-version is specified, the latest local version is used. In all other cases, the latest record is fetched from the remote host.

DCC_NUMBER

The number for the DCC record to view.

-s, --archive-dir

Directory to use to archive and retrieve downloaded documents and files. If not specified, the DCC_ARCHIVE environment variable is used if set, otherwise defaults to the system’s temporary directory (e.g. /tmp on Linux). To persist archive data across invocations of the tool, ensure this option is set.

--ignore-version

Attempt to fetch the latest version of the document specified in DCC_NUMBER from the local archive regardless of the version specified. If no local version exists, the version of the document given in DCC_NUMBER (or, if no version is specified, the latest version) will still be fetched from the DCC.

-f, --force

Force retrieval of a record or file from the remote DCC host even if it exists in the local archive. The locally archived record or file is overwritten with the retrieved version.

--host

The DCC host to use. If not specified, the DCC_HOST environment variable is used if set, otherwise https://dcc.ligo.org/.

--idp-host

The identity provider host to use. If not specified, the ECP_IDP environment variable is used if set, otherwise https://login.ligo.org/.

--public

Only attempt to retrieve public DCC records. This should avoid triggering an authentication check.

-v, --verbose

Increase the program’s verbosity. This can be specified multiple times to further increase verbosity.

-q, --quiet

Decrease the program’s verbosity. This can be specified multiple times to further decrease verbosity.

--debug

Show full exceptions when errors are encountered.

Environment variables

DCC_ARCHIVE

See also

Configuring a local archive

The path to a local directory to use to archive downloaded records and files.

DCC_HOST

See also

Changing the DCC or login host

The DCC host to use.

ECP_IDP

See also

Changing the DCC or login host

The identity provider host to use.