{"id":17436285,"url":"https://github.com/ngageoint/seed-cli","last_synced_at":"2025-07-17T06:08:42.705Z","repository":{"id":56352467,"uuid":"99388003","full_name":"ngageoint/seed-cli","owner":"ngageoint","description":"Algorithm developer CLI supporting Seed compliant image publish and testing.","archived":false,"fork":false,"pushed_at":"2020-11-12T20:07:23.000Z","size":9218,"stargazers_count":5,"open_issues_count":21,"forks_count":5,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-29T04:42:55.836Z","etag":null,"topics":["algorithms","cli","containers","discovery","docker","scale","seed"],"latest_commit_sha":null,"homepage":"https://ngageoint.github.io/seed","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ngageoint.png","metadata":{"files":{"readme":"readme.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-05T00:05:16.000Z","updated_at":"2020-11-12T18:58:15.000Z","dependencies_parsed_at":"2022-08-15T17:10:26.854Z","dependency_job_id":null,"html_url":"https://github.com/ngageoint/seed-cli","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngageoint%2Fseed-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngageoint%2Fseed-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngageoint%2Fseed-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngageoint%2Fseed-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngageoint","download_url":"https://codeload.github.com/ngageoint/seed-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249191900,"owners_count":21227674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","cli","containers","discovery","docker","scale","seed"],"created_at":"2024-10-17T10:08:08.721Z","updated_at":"2025-04-16T03:43:20.622Z","avatar_url":"https://github.com/ngageoint.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Seed CLI\n\nimage:https://badges.gitter.im/ngageoint/seed.svg[link=\"https://gitter.im/ngageoint/seed?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\"]\nimage:https://travis-ci.org/ngageoint/seed-cli.svg?branch=master[link=\"https://travis-ci.org/ngageoint/seed-cli\"]\n\n:seed-user-guide-url: https://ngageoint.github.io/seed-cli\n\n//# tag::intro[]\nThe Seed team provides a fully featured Command-Line Interface (CLI) for algorithm developers looking to offer Seed\ncompliant packaging of their jobs. Using the CLI will enable you to quickly iterate without getting bogged down\nlearning how to interface directly with the underlying container technologies (Docker). It also simplifies the process\nof attaching Seed metadata to your algorithm prior to publish.\n\nThe following sections provide a brief overview of the most commonly used Seed CLI commands.\nFor more detailed explanations, refer to the Seed {seed-user-guide-url}[user guide].\n//# end::intro[]\n\n== Usage\n\n//# tag::command-intro[]\nSeed CLI offers sub-commands that correlate to common operations performed by an algorithm developer. These\ncan be seen from the command-line by launching the CLI without any arguments:\n//# end::command-intro[]\n\n----\nseed\n----\n\nNote that many seed commands call docker in the background, and those docker commands often require elevated privileges. \nWhen necessary, seed will attempt to run these commands as sudo and you may be prompted for a password.\n\nThe full list of available commands will be returned as output. High-level overview of each command and its expected\nusage can be found in the following sections.\n\n=== Build\n\n//# tag::build-usage[]\nThe first step when starting to package an algorithm for Seed compliance is to define the requirements and interface.\nThis is done by a combination of execution environment configuration (`Dockerfile`), resource requirement definition and\ninput / output specification (`seed.manifest.json`). By default, the `seed build` command assumes both a `Dockerfile`\n`seed.manifest.json` reside in the current working directory. Using these two files in conjunction the build command\nis able to construct an re-usable Seed compliant image.\n//# end::build-usage[]\n\n//# tag::build-example[]\nA simple example of this would be the addition-job image.\n\n----\nseed build -d examples/addition-job\n----\n\nThis will result in a new Docker image that contains `com.ngageoint.seed.manifest` LABEL and is named according to spec\nconstraint: addition-job-0.0.1-seed:1.0.0\n\nThis image can now be executed via the `seed run` command or pushed to a remote image registry by way of `seed publish`.\n//# end::build-example[]\n\n//# tag::build-publish-usage[]\nThe seed build command also provides the option to automatically publish the image after building via the `-publish` flag. \nAll flags specified by the `seed publish` command are available for use.\n//# end::build-publish-usage[]\n\n=== Init\n\n//# tag::init-usage[]\nThe init command will initalize a directory with a template seed.manifest.json file.  \n//# end::init-usage[]\n\n//# tag::init-example[]\nThe following command will put a template seed.manifest.json file in the examples/job directory:\n\n----\nseed init -d examples/job\n----\n//# end::init-example[]\n\n=== Run\n\n//# tag::run-usage[]\nThe primary purpose of the CLI is to easily enable algorithm execution. The common stumbling blocks for new developers\nare being able to feed data into and retrieve out of the containers as a part of execution. The `seed run` command\nfacilitates this through introspection of the Seed interface indicating exactly what input data is required, allowing\nfor simply specifying the system locations of data and handling all mounting and output validation and capture\noperations for the developer.\n\nIf gpu resources are requested in the seed manifest file then `seed run` will automatically attempt to allocate the requested GPU resources. \nNvidia-docker(2.0) not being installed or insufficient GPU resources available will result in a docker error.   \nInstructions for installing nvidia-docker(2.0) can be found here: https://github.com/NVIDIA/nvidia-docker/wiki/Installation-(version-2.0)\n//# end::run-usage[]\n\n//# tag::run-example[]\nFor a Seed interface with a single `inputData.files` element with a `name` of `MY_INPUT` the `seed run` command would\nbe as follows:\n\n----\nseed run -in process-file:0.1.0-seed:0.1.0 -i MY_INPUT=/tmp/file_input.txt -o /tmp/outputs\n----\n\nThis will volume mount `/tmp/file_input.txt` as read only and `/tmp/outputs` into the container, replacing these values\nwith the container relative locations and injecting into the defined `args` placeholders for consumption by the\nalgorithm.\n//# end::run-example[]\n\n=== Batch\n\n//# tag::batch-usage[]\nRelated to the run command, the `seed batch` command will run an image multiple times with varying inputs.  It will take\nan image name and either a directory with files to use as input or a csv file specifying keys and files (preferred).\n//# end::batch-usage[]\n\n//# tag::batch-example[]\nFor an Seed interface with two `inputData.files` elements with a `name` of `MY_INPUT` and `MY_INPUT2` the `seed batch` command would\nbe as follows:\n\n----\nseed batch -in process-file:0.1.0-seed:0.1.0 -b batch.csv -o /tmp/outputs\n----\n\nand the batch.csv file would look something like this:\n\n....\nMY_INPUT, MY_INPUT2\n/path/to/input1.txt, input2.txt\n/path/to/different/input.txt, input2.txt\ncurrentDirectoryInput.txt, input2.txt\n....\n\nThe image will be run three times and success or failure will be reported for each run along with the location of any\noutput.\n//# end::batch-example[]\n\n=== List\n\nSimple command to list the local Seed compliant images.  It can be run with the following command:\n\n----\nseed list\n----\n\n=== Search\n\n//# tag::search-usage[]\nAllows for discovery of Seed compliant images hosted within a Docker registry (default is docker.io). \n//# end::search-usage[]\n\n//# tag::search-example-1[]\nThe 'seed search' command will search a given registry for repositories (images and all their versions) that end in \n\"-seed\".  Here is an example of searching quay.io:\n\n----\nseed search -r https://quay.io\n----\n//# end::search-example-1[]\n\n//# tag::search-example-2[]\nIf no registry url is supplied, the search command uses docker hub, which requires a organization (or user) to be specified:\n\n----\nseed search -o geoint\n----\n//# end::search-example-2[]\n\n//# tag::search-example-3[]\nIf a registry is private, a username and password can be specified with -u and -p options:\n\n----\nseed search -r http://localhost:5000 -u testuser -p testpassword\n----\n//# end::search-example-3[]\n\n=== Publish\n\n//# tag::publish-usage[]\nProvides a convenient way for algorithm developers to push a Seed image to a registry.  This command will tag a seed\nimage appropriately and push it to the specified registry.  If successful, it will then remove the local image as well.\n//# end::publish-usage[]\n\n//# tag::publish-example-1[]\nHere is an example of publishing the extractor image to the geoint organization on docker hub:\n\n----\nseed publish -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint\n----\n//# end::publish-example-1[]\n\n//# tag::publish-example-2[]\nPublishing will check if an image with the same name and tag exists in the registry and will fail if one is found unless\neither the force flag (-f) is set or a deconflict tag is specified to increase a version number.  A common use case for\nseed algorithm developers is to publish new versions of their image and this can be done by specifying one of the job or\npackage version flags.  Here is an example of updating the extractor image to 1.0.0:\n\n----\nseed publish -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint -A -P\n----\n//# end::publish-example-2[]\n\n//# tag::publish-example-3[]\nThis will rebuild the extractor image with the appropriate name \u0026 label and publish the image extractor-1.0.0-seed:1.0.0\nto docker hub.  Finally, if the registry is private, a username and password can be specified with -u and -p options:\n\n----\nseed publish -in extractor-0.1.0-seed:0.1.0 -r localhost:5000 -u testuser -p testpassword\n----\n//# end::publish-example-3[]\n\n=== Pull\n\nThe Pull command will pull the a Seed compliant image from the remote Docker registry. \n\n//# tag::pull-example[]\nThis will pull the extractor-0.1.0-seed:1.0.0 image from the docker.io/geoint registry:\n----\nseed pull -in extractor-0.1.0-seed:0.1.0 -r docker.io -o geoint\n----\n//# end::pull-example[]\n\n=== Validate\n\n//# tag::validate-usage[]\nThe Validate command will validate a Seed json file against the Seed schema.  This is also done as part of the build and\nrun commands, but if a user is having problems getting their Seed file to validate this can be useful to debug without\nthose additional steps.\n//# end::validate-usage[]  \n\n//# tag::validate-example-1[]\nThis command will validate the Seed file in the examples/extractor directory using the schema built-in to the Seed CLI tool:\n\n----\nseed validate -d examples/extractor\n----\n//# end::validate-example-1[]\n\n//# tag::validate-example-2[]\nTo use a different schema, pass it in using the -s flag:\n\n----\nseed validate -d examples/extractor -s schema/0.1.0/seed.manifest.schema.json\n----\n//# end::validate-example-2[]\n\n=== Version\n//# tag::version[]\nThe version command will print the version of the Seed CLI tool:\n\n----\nseed version\n----\n//# end::version[]\n\n== Development\n\nIf you wish develop on the Seed CLI, you will need an installation of Golang 1.6+ (for vendoring support). Once you have a `GOPATH` defined, the following will allow you to clone and build the CLI project:\n\n----\n# Clone repo and retrieve dependencies\ngit clone https://github.com/ngageoint/seed-cli.git $GOPATH/src/github.com/ngageoint/seed-cli\ncd $GOPATH/src/github.com/ngageoint/seed-cli\ngo get ./...\n\n# Build binary\n./build-cli.sh\n\n# Optionally add it to your local system binary folder for easy execution\ncp -f output/seed-linux-amd64 /usr/local/bin/seed\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngageoint%2Fseed-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngageoint%2Fseed-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngageoint%2Fseed-cli/lists"}