[ARVADOS] created: 204419e149d2b6b19b3bc2965e1c524b7abd5881
git at public.curoverse.com
git at public.curoverse.com
Tue Nov 11 16:53:36 EST 2014
at 204419e149d2b6b19b3bc2965e1c524b7abd5881 (commit)
commit 204419e149d2b6b19b3bc2965e1c524b7abd5881
Author: Ward Vandewege <ward at curoverse.com>
Date: Tue Nov 11 16:53:02 2014 -0500
Add some basic documentation for the arv subcommands.
refs #4486
diff --git a/doc/_config.yml b/doc/_config.yml
index 0b1645f..6d2c895 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -69,6 +69,8 @@ navbar:
- sdk/go/index.html.textile.liquid
- CLI:
- sdk/cli/index.html.textile.liquid
+ - sdk/cli/install.html.textile.liquid
+ - sdk/cli/subcommands.html.textile.liquid
api:
- Concepts:
- api/index.html.textile.liquid
diff --git a/doc/sdk/cli/index.html.textile.liquid b/doc/sdk/cli/index.html.textile.liquid
index 73acddc..6b0af21 100644
--- a/doc/sdk/cli/index.html.textile.liquid
+++ b/doc/sdk/cli/index.html.textile.liquid
@@ -2,59 +2,17 @@
layout: default
navsection: sdk
navmenu: CLI
-title: "Command line SDK"
+title: "Overview"
...
-The @arv@ CLI tool provides a generic set of wrappers so you can make API calls easily. It performs some validation before connecting to the API server: for example, it refuses to do an API call if a required parameter is missing.
+The @arv@ CLI tool provides a generic set of wrappers so you can make API calls easily. Additionally, it provides access to a number of subcommands.
-It also provides access to Keep storage services with the @arv keep@ subcommand.
-
-h3. Usage
+h3. Wrapper for API calls
See the "command line interface":{{site.baseurl}}/user/reference/sdk-cli.html page in the user guide.
-h3. Installation
-
-If you are logged in to an Arvados VM, the @arv@ should be installed.
-
-To use @arv@ elsewhere, you can either install the @arvados-cli@ gem via RubyGems or build and install the package using the arvados source tree.
-
-h4. Prerequisites: Ruby >= 2.0.0 and curl libraries
-
-You can use "RVM":http://rvm.io/rvm/install to install and manage Ruby versions.
-
-<notextile>
-<pre>
-$ <code class="userinput">sudo apt-get install curl</code>
-$ <code class="userinput">sudo sh -c 'curl -sSL https://get.rvm.io | bash -s stable'</code>
-$ <code class="userinput">source /etc/profile.d/rvm.sh</code>
-</pre>
-</notextile>
-
-Install curl libraries with your system's package manager. For example, with Debian or Ubuntu:
-
-<notextile>
-<pre>
-$ <code class="userinput">sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev</code>
-</pre>
-</notextile>
-
-h4. Option 1: install with RubyGems
-
-<notextile>
-<pre>
-$ <code class="userinput">sudo gem install arvados-cli</code>
-</pre>
-</notextile>
+h3. Subcommands
-h4. Option 2: build and install from source
+See the "arv subcommands":{{site.baseurl}}/sdk/cli/subcommands.html page.
-<notextile>
-<pre>
-$ <code class="userinput">git clone https://github.com/curoverse/arvados.git</code>
-$ <code class="userinput">cd arvados/sdk/cli</code>
-$ <code class="userinput">gem build arvados-cli.gemspec</code>
-$ <code class="userinput">sudo gem install arvados-cli-*.gem</code>
-</pre>
-</notextile>
diff --git a/doc/sdk/cli/install.html.textile.liquid b/doc/sdk/cli/install.html.textile.liquid
new file mode 100644
index 0000000..ff19428
--- /dev/null
+++ b/doc/sdk/cli/install.html.textile.liquid
@@ -0,0 +1,42 @@
+---
+layout: default
+navsection: sdk
+navmenu: CLI
+title: "Installation"
+
+...
+
+If you are logged in to an Arvados VM, the @arv@ tool should be installed.
+
+To use @arv@ elsewhere, you can either install the @arvados-cli@ gem via RubyGems or build and install the package from source.
+
+h4. Prerequisites: Ruby >= 2.1.0 and curl libraries
+
+Make sure you have "Ruby and bundler":/install/install-manual-prerequisites-ruby.html installed.
+
+Install curl libraries with your system's package manager. For example, on Debian or Ubuntu:
+
+<notextile>
+<pre>
+$ <code class="userinput">sudo apt-get install libcurl3 libcurl3-gnutls libcurl4-openssl-dev</code>
+</pre>
+</notextile>
+
+h4. Option 1: install with RubyGems
+
+<notextile>
+<pre>
+$ <code class="userinput">sudo gem install arvados-cli</code>
+</pre>
+</notextile>
+
+h4. Option 2: build and install from source
+
+<notextile>
+<pre>
+$ <code class="userinput">git clone https://github.com/curoverse/arvados.git</code>
+$ <code class="userinput">cd arvados/sdk/cli</code>
+$ <code class="userinput">gem build arvados-cli.gemspec</code>
+$ <code class="userinput">sudo gem install arvados-cli-*.gem</code>
+</pre>
+</notextile>
diff --git a/doc/sdk/cli/subcommands.html.textile.liquid b/doc/sdk/cli/subcommands.html.textile.liquid
new file mode 100644
index 0000000..201eb24
--- /dev/null
+++ b/doc/sdk/cli/subcommands.html.textile.liquid
@@ -0,0 +1,248 @@
+---
+layout: default
+navsection: sdk
+navmenu: CLI
+title: "arv subcommands"
+
+...
+
+The @arv@ CLI tool provides access to a number of subcommands which are described on this page.
+
+h3(#arv-create). arv create
+
+ at arv create@ can be used to create Arvados objects from the command line. Arv create opens up the editor of your choice (set the EDITOR environment variable) and allows you to type or paste a json or yaml description. When saved the object will be created on the API server, if it passes validation.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv create --help</code>
+Options:
+ --project-uuid, -p <s>: Project uuid in which to create the object
+ --help, -h: Show this message
+</pre>
+</notextile>
+
+h3(#arv-edit). arv edit
+
+ at arv edit@ can be used to edit Arvados objects from the command line. Arv edit opens up the editor of your choice (set the EDITOR environment variable) with the json or yaml description of the object. Saving the file will update the Arvados object on the API server, if it passes validation.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv edit --help</code>
+Arvados command line client
+Usage: arv edit [uuid] [fields...]
+
+Fetch the specified Arvados object, select the specified fields,
+open an interactive text editor on a text representation (json or
+yaml, use --format) and then update the object. Will use 'nano'
+by default, customize with the EDITOR or VISUAL environment variable.
+</pre>
+</notextile>
+
+h3(#arv-copy). arv copy
+
+ at arv copy@ can be used to copy a pipeline instance, template or collection from one Arvados instance to another. It takes care of copying the object and all its dependencies.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv copy --help</code>
+usage: arv-copy [-h] [-v] [--progress] [--no-progress] [-f] --src
+ SOURCE_ARVADOS --dst DESTINATION_ARVADOS [--recursive]
+ [--no-recursive] [--dst-git-repo DST_GIT_REPO]
+ [--project-uuid PROJECT_UUID] [--retries RETRIES]
+ object_uuid
+
+Copy a pipeline instance, template or collection from one Arvados instance to
+another.
+
+positional arguments:
+ object_uuid The UUID of the object to be copied.
+
+optional arguments:
+ -h, --help show this help message and exit
+ -v, --verbose Verbose output.
+ --progress Report progress on copying collections. (default)
+ --no-progress Do not report progress on copying collections.
+ -f, --force Perform copy even if the object appears to exist at
+ the remote destination.
+ --src SOURCE_ARVADOS The name of the source Arvados instance (required).
+ May be either a pathname to a config file, or the
+ basename of a file in
+ $HOME/.config/arvados/instance_name.conf.
+ --dst DESTINATION_ARVADOS
+ The name of the destination Arvados instance
+ (required). May be either a pathname to a config file,
+ or the basename of a file in
+ $HOME/.config/arvados/instance_name.conf.
+ --recursive Recursively copy any dependencies for this object.
+ (default)
+ --no-recursive Do not copy any dependencies. NOTE: if this option is
+ given, the copied object will need to be updated
+ manually in order to be functional.
+ --dst-git-repo DST_GIT_REPO
+ The name of the destination git repository. Required
+ when copying a pipeline recursively.
+ --project-uuid PROJECT_UUID
+ The UUID of the project at the destination to which
+ the pipeline should be copied.
+ --retries RETRIES Maximum number of times to retry server requests that
+ encounter temporary failures (e.g., server down).
+ Default 3.
+</pre>
+</notextile>
+
+h3(#arv-tag). arv tag
+
+ at arv tag@ is used to tag Arvados objects.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv tag --help</code>
+arvados cli client
+ --dry-run, -n: Don't actually do anything
+ --verbose, -v: Print some things on stderr
+ --uuid, -u: Return the UUIDs of the objects in the response, one per
+ line (default)
+ --json, -j: Return the entire response received from the API server, as
+ a JSON object
+ --human, -h: Return the response received from the API server, as a JSON
+ object with whitespace added for human consumption
+ --pretty, -p: Synonym of --human
+ --yaml, -y: Return the response received from the API server, in YAML
+ format
+ --help, -e: Show this message
+</pre>
+</notextile>
+
+
+h3(#arv-ws). arv ws
+
+ at arv ws@ provides access to the websockets event stream.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv ws --help</code>
+usage: arv-ws [-h] [-u UUID] [-f FILTERS]
+ [--poll-interval POLL_INTERVAL | --no-poll]
+ [-p PIPELINE | -j JOB]
+
+optional arguments:
+ -h, --help show this help message and exit
+ -u UUID, --uuid UUID Filter events on object_uuid
+ -f FILTERS, --filters FILTERS
+ Arvados query filter to apply to log events (JSON
+ encoded)
+ --poll-interval POLL_INTERVAL
+ If websockets is not available, specify the polling
+ interval, default is every 15 seconds
+ --no-poll Do not poll if websockets are not available, just fail
+ -p PIPELINE, --pipeline PIPELINE
+ Supply pipeline uuid, print log output from pipeline
+ and its jobs
+ -j JOB, --job JOB Supply job uuid, print log output from jobs
+</pre>
+</notextile>
+
+h3(#arv-keep). arv keep
+
+ at arv keep@ provides access to the Keep storage service.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv keep --help</code>
+Usage: arv keep [method] [--parameters]
+Use 'arv keep [method] --help' to get more information about specific methods.
+
+Available methods: ls, get, put, less, check, docker
+</pre>
+</notextile>
+
+h3(#arv-pipeline-run). arv pipeline run
+
+ at arv pipeline run@ can be used to start a pipeline run from the command line.
+
+The User Guide has a page with a bit more information on "using arv pipeline run":{{site.baseurl}}/user/topics/running-pipeline-command-line.html.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv pipeline run --help</code>
+Options:
+ --dry-run, -n: Do not start any new jobs or wait for existing jobs to
+ finish. Just find out whether jobs are finished,
+ queued, or running for each component.
+ --status-text <s>: Store plain text status in given file. (Default:
+ /dev/stdout)
+ --status-json <s>: Store json-formatted pipeline in given file. (Default:
+ /dev/null)
+ --no-wait: Do not wait for jobs to finish. Just look up status,
+ submit new jobs if needed, and exit.
+ --no-reuse: Do not reuse existing jobs to satisfy pipeline
+ components. Submit a new job for every component.
+ --debug, -d: Print extra debugging information on stderr.
+ --debug-level <i>: Set debug verbosity level.
+ --template <s>: UUID of pipeline template, or path to local pipeline
+ template file.
+ --instance <s>: UUID of pipeline instance.
+ --submit: Submit the pipeline instance to the server, and exit.
+ Let the Crunch dispatch service satisfy the components
+ by finding/running jobs.
+ --run-pipeline-here: Manage the pipeline instance in-process. Submit jobs
+ to Crunch as needed. Do not exit until the pipeline
+ finishes (or fails).
+ --run-jobs-here: Run jobs in the local terminal session instead of
+ submitting them to Crunch. Implies
+ --run-pipeline-here. Note: this results in a
+ significantly different job execution environment, and
+ some Crunch features are not supported. It can be
+ necessary to modify a pipeline in order to make it run
+ this way.
+ --run-here: Synonym for --run-jobs-here.
+ --description <s>: Description for the pipeline instance.
+ --version, -v: Print version and exit
+ --help, -h: Show this message
+</pre>
+</notextile>
+
+h3(#arv-run). arv run
+
+The @arv-run@ command creates Arvados pipelines at the command line that fan out to multiple concurrent tasks across Arvado compute nodes.
+
+The User Guide has a page on "using arv-run":{{site.baseurl}}/user/topics/arv-run.html.
+
+<notextile>
+<pre>
+$ <code class="userinput">arv run --help</code>
+usage: arv-run [-h] [--retries RETRIES] [--dry-run] [--local]
+ [--docker-image DOCKER_IMAGE] [--ignore-rcode] [--no-reuse]
+ [--no-wait] [--project-uuid PROJECT_UUID] [--git-dir GIT_DIR]
+ [--repository REPOSITORY] [--script-version SCRIPT_VERSION]
+ ...
+
+positional arguments:
+ args
+
+optional arguments:
+ -h, --help show this help message and exit
+ --retries RETRIES Maximum number of times to retry server requests that
+ encounter temporary failures (e.g., server down).
+ Default 3.
+ --dry-run Print out the pipeline that would be submitted and
+ exit
+ --local Run locally using arv-run-pipeline-instance
+ --docker-image DOCKER_IMAGE
+ Docker image to use, default arvados/jobs
+ --ignore-rcode Commands that return non-zero return codes should not
+ be considered failed.
+ --no-reuse Do not reuse past jobs.
+ --no-wait Do not wait and display logs after submitting command,
+ just exit.
+ --project-uuid PROJECT_UUID
+ Parent project of the pipeline
+ --git-dir GIT_DIR Git repository passed to arv-crunch-job when using
+ --local
+ --repository REPOSITORY
+ repository field of component, default 'arvados'
+ --script-version SCRIPT_VERSION
+ script_version field of component, default 'master'
+</pre>
+</notextile>
+
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list