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:
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
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 |
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
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
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
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 ~