DMF Command-line interface

Overview

The DMF command-line interface (CLI) is used to perform common start-up, browsing, etc. tasks.

Getting started

Note

In the examples that follow the terminal shell prompt will be represented by a $. It will be omitted in cases where there is no terminal output shown.

To use the CLI, open a shell window and run “dmf <command>”. For example, to see the help message, run:

dmf -h

All operations in the DMF occur in the context of a base container called a “workspace”. This container has a configuration and all the metadata and files, called “resources”. A workspace corresponds to a directory on the filesystem. You can have many workspaces, but only one is active at a time. To choose the currently active workspace, you can specify it explicitly for each command, e.g.:

dmf -p /path/to/workspace <commands...>

But this quickly becomes tedious. It is easier to use the DMF’s global configuration to set the current workspace with the “init” command:

dmf init /path/to/workspace

After you run this command, subsequent commands will operate within this workspace. To create a blank workspace to run in, use “dmf create”:

dmf create /path/to/workspace --name "MyWorkspace" --description "My first workspace"

You’ll notice that this command prints out some information about the workspace at the end. To see that same information at any time for your current workspace, use “dmf info”:

$ dmf info

Workspace
  MyWorkspace - My first workspace

General information
 - Location = /home/dang/src/workspace
 - Workspace identifier (_id) = 2f0a82e03e5747ccbcb04f83cb417f5a
 - Created = 2018-07-07 07:10:02
 - Modified = 2018-07-07 07:10:02
 - Num. resources = 0

Configuration
 - conf = None
 - htmldocs = ['/home/dang/src/idaes/doc/build/html']
 - showver = False

To see the contents of a workspace, a.k.a. the workspace resources, you can use the “dmf ls”. This will be quite boring if you just created the workspace, since there are no resources in it yet:

$ dmf ls
$

To see some results from the listing, use “dmf import” to add a generic file resouce to the workspace and then try again with “ls”:

$ echo 'hello' > hello.txt  # create the text file
$ dmf import hello.txt
Imported 1 resource
$ dmf ls
hello.txt:data

Command reference

The DMF command-line interface (CLI) uses the main command / subcommand interface that many people will know from tools such as git and subversion. The main command is dmf. The subcommands are:

Divider

dmf create

usage: dmf create [-h] [-v] [-c PATH] [--interactive] [--htmldocs VALUE]
                  [--description VALUE] [--name VALUE]
                  path

Positional Arguments

path Directory for new workspace. In this directory, a directory “config.yaml” will be created to hold metadata.

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)
--interactive, -i
 

Interactively ask for configuration values

Default: False

--htmldocs

HTML documentation paths. Each item is a directory containing Sphinx-generated HTML docs (repeatable)

Default: [‘{dmf_root}/doc/build/html’]

--description

A human-readable description of the workspace

Default: “”

--name

A short name for the workspace

Default: “”

Examples:

Interactively create a new workspace:
dmf create -i $HOME/data/my-workspace

Divider

dmf import

usage: dmf import [-h] [-v] [-c PATH] [-p PATH] [-x] [FILE [FILE ...]]

Positional Arguments

FILE

One or more files, or patterns of files, to import (default=empty)

Default: []

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)
-p, --path Use workspace at PATH (default = from config or “.”)
-x, --exitfirst
 

Exit on first error

Default: False

Divider

dmf info

usage: dmf info [-h] [-v] [-c PATH] [PATH]

Positional Arguments

PATH Search for DMF configuration at PATH (default=”.”)

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)

Examples:

Get info about current workspace:
dmf info
Get info about “~/data” directory:
dmf info -p ~/data

Divider

dmf init

usage: dmf init [-h] [-v] [-c PATH] [WORKSPACE]

Positional Arguments

WORKSPACE Set path to default workspace

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)

Examples:

Print current settings:
dmf init
Print settings from “/opt/dmf”
dmf init -c /opt/dmf
Set workspace to “~/data/project/my-dmf”
dmf init ~/data/project/my-dmf

Divider

dmf ls

usage: dmf ls [-h] [-v] [-c PATH] [-l] [-r] [PATH]

Positional Arguments

PATH List resources in workspace at PATH (default = from config or “.”)

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)
-l, --long

Use a long listing format

Default: False

-r, --relations
 

With long listing, show relationships

Default: False

Examples:

List objects in current workspace:
dmf ls
List objects, in long format, in workspace at $HOME/foo:
dmf ls -l $HOME/foo
List objects and their relations (in long format):
dmf ls -lr

Divider

dmf ws

usage: dmf ws [-h] [-v] [-c PATH] [-p PATH]

Named Arguments

-v, --verbose Default: 0
-c, --conf Use global config at PATH (default = ~/.dmf)
-p, --path

List workspaces at/below PATH (default = “.”)

Default: “.”

Examples:

List workspaces below current directory:
dmf ws
List workspaces below user $HOME directory:
dmf ws -p ~