ivcap-cli

IVCAP - A Command-line Tool to interact with an IVCAP deployment

IVCAP is helping researchers better investigate their domains and derive new insights by collecting, processing and analysing multi-modal and multi-scale data and better facilitating data provenance and thereby fostering interdisciplinary collaboration.

IVCAP has an extensive REST API which is usually called directly from applications or scientific notebooks. However, to support simple data operation from the command line, we developed this simple command-line tool. It only covers the subset of the IVCAP API, but we would be very excited to receive pull requests to extend it's functionality or fix bugs.

• Install released binaries
• Usage
  • Context
    • Projects
    • Accounts
    • Capabilities
    • Invitations
  • Who am I
  • Service
  • Job
  • Artifact
  • Collections
  • DataFabric
  • Nextflow
  • Queues
  • Secrets
  • Package
  • Genomes
• Agent / automation usage
  • MCP-Provisioned Skills (Resources + Prompts)
• Build from source

Install Released Binaries

There are ready to use binaries for some architectures available at the repo's release tab.

If you use homebrew, you can install it by:

brew tap brew tap ivcap-works/ivcap
brew install ivcap

Usage

The first order of business is setting up a context for a specific IVCAP deployment. You can also configure multiple contexts, allowing the same ivcap CLI to interact with multiple IVCAP deployments (and switch between them).

This tool can also be used as a local MCP server (see Agent / automation usage).

Built-in MCP tools also include helpers for working with Nextflow services:

• nextflow_create: assemble a Nextflow pipeline package .tar.gz from a list of sources (text/base64/url/artifact), upload it as an artifact, validate ivcap-tool.yaml, and publish/update the service description aspect.
• nextflow_run: create a job for a Nextflow service from either an inline input payload or a request-aspect URN.

A command line tool to to more conveniently interact with the
API exposed by a specific IVCAP deployment.

Usage:
  ivcap [flags]
  ivcap [command]

Commands:
  artifact      Create and manage artifacts
  collection    Create and manage collections
  context       Manage deployment access, projects, and accounts
  datafabric    Query the datafabric and create and manage aspects within
  genome        Look up, download and import genomes from NCBI
  job           Create and manage jobs
  nextflow      Commands for working with Nextflow-based services
  package       Push/pull and manage service packages
  queue         Create and manage queues
  secret        Set and list secrets
  service       Create and manage services
  whoami        Show the currently authenticated identity and accessible accounts/projects

Agent support commands:
  agent-context Print embedded agent context guidance (markdown)
  mcp           Start an MCP server for accessing all tools on an IVCAP platform
  skills        List and show agent skill docs embedded in this CLI release

General support commands:
  completion    Generate the autocompletion script for the specified shell
  help          Help about any command

Flags:
      --access-token string   Access token to use for authentication with API server [IVCAP_ACCESS_TOKEN]
      --context string        Context (deployment) to use
      --debug                 Set logging level to DEBUG
  -h, --help                  help for ivcap
      --no-history            Do not store history
  -o, --output string         Set format for displaying output [json, yaml]
      --silent                Do not show any progress information
      --timeout int           Max. number of seconds to wait for completion (default 30)
  -v, --version               version for ivcap

Use "ivcap [command] --help" for more information about a command.

Configure context for a specific deployment

With the following command we are creating a context named sd-dev for the IVCAP deployment at https://develop.ivcap.net. Please check first the details of deployment you want to use.

% ivcap context create sd-dev https://develop.ivcap.net
Context 'sd-dev' created.

If we have multiple contexts, we can easily switch with context set

% ivcap context set sd-dev
Switched to context 'sd-dev'.

The following command lists all the configured contexts:

% ivcap context list
+---------+-----------+-----------------------------+--------------------------------+
| CURRENT | NAME      | ACCOUNTID                   | URL                            |
+---------+-----------+-----------------------------+--------------------------------+
| *       | sd-dev     | urn:ivcap:account:4c65b865  | <http://develop.ivcap.net> |
+---------+-----------+-----------------------------+--------------------------------+

To obtain an authorisation token, some deployments provide a username/password based identity provider.

% ivcap context login


    █▀▀▀▀▀█    ▀█  ▄▀▄▀▀ ▄▄▀▄ █▀▀▀▀▀█
    █ ███ █ █  █▀ ▀█▀ █  ▀▀█  █ ███ █
    █ ▀▀▀ █ █ ▀▀▄▀▀▀▀█▀ ▀█ ▀▀ █ ▀▀▀ █
    ▀▀▀▀▀▀▀ █▄█ █ █ █ █ █▄█ ▀ ▀▀▀▀▀▀▀
    █ ██▀▀▀▄▄▄ ▄ ██ ██▄█▀▄█▄█ ██▀██ ▄
    █▀▄▄ ▀▀  █ █▀█▀▀▀█▄  █  █ ▄ █▄█▀
...
To login to the IVCAP Service, please go to:  https://id-provider.com/activate?user_code=....
or scan the QR Code to be taken to the login page
Waiting for authorisation...

The context command also serves as the home for all identity and access management (IAM) operations. Running ivcap context --help shows two groups:

Deployment management:
  create    Create a new named context
  list      List all saved contexts
  set       Switch active context
  get       Show current context details
  login     Authenticate via OIDC
  logout    Clear stored tokens

Access management:
  project      Manage projects and select the current one
  account      Manage accounts you belong to
  invitation   Respond to invitations addressed to you
  capabilities List capabilities grantable on projects and accounts

All subcommands carry short aliases so common operations stay concise:

• ivcap c login — authenticate
• ivcap c p use — switch active project (interactive picker)
• ivcap c a list — list your accounts

Follow this link for more details about the context command.

Projects

Projects scope the resources (artifacts, jobs, services) you work with. The active project is recorded in the context and forwarded to the platform on every request.

% ivcap context project list
% ivcap context project use          # interactive picker
% ivcap context project use <id>     # set directly
% ivcap context project create --name "My Project"

Member management:

% ivcap context project members <project-id>
% ivcap context project invite <project-id> --email user@example.com --capability write
% ivcap context project grant <project-id> --user <urn> --capability write
% ivcap context project revoke-capability <project-id> --user <urn> --capability write
% ivcap context project remove-member <project-id> --user <urn>

Follow this link for more details about the project command.

Accounts

Accounts are the top-level organisational unit. A project always belongs to an account.

% ivcap context account list
% ivcap context account get <account-id>
% ivcap context account create --name "My Org"

Member management:

% ivcap context account members <account-id>
% ivcap context account invite <account-id> --email user@example.com --capability create_project
% ivcap context account grant <account-id> --user <urn> --capability manage_members
% ivcap context account revoke-capability <account-id> --user <urn> --capability manage_members
% ivcap context account remove-member <account-id> --user <urn>

Follow this link for more details about the account command.

Capabilities

Lists the capability vocabulary accepted by grant and invite commands:

% ivcap context capabilities                    # show all
% ivcap context capabilities --kind project     # project capabilities only
% ivcap context capabilities --kind account     # account capabilities only

Follow this link for more details.

Invitations

Invitations you have received (from any project or account):

% ivcap context invitation list
% ivcap context invitation accept <invitation-id>
% ivcap context invitation decline <invitation-id>
% ivcap context invitation revoke <invitation-id>   # cancel one you issued

Follow this link for more details.

Who am I

Displays the currently authenticated identity along with the active project and all accessible accounts and projects:

% ivcap whoami

         Email  user@example.com
          Name  Alex Smith
  Current Proj  urn:ivcap:project:abc123 (My Project)
       Account  urn:ivcap:account:def456 (My Org)

Supports --output json / --output yaml for programmatic use.

Follow this link for more details.

Service

To list all available services:

% ivcap services list --limit 2
+----+--------------------------+------------------------------------------------------------------+
| ID | NAME                     | DESCRIPTION                                                      |
+----+--------------------------+------------------------------------------------------------------+
| @1 | llama-index-agent-runner | Executes queries or chats with LlamaIndex agents.                |
+----+--------------------------+------------------------------------------------------------------+
| @2 | gene-whisperer           | A tool for answering genomic questions. Collates information     |
|    |                          | across various sources such as NCBI, UniProt, Blast and          |
|    |                          | GeneOntology to answer biomedical questions.                     |
+----+--------------------------+------------------------------------------------------------------+

Note on @… IDs: values like @1 are local history aliases for the actual resource URNs returned by the platform. You can typically reference @1 in subsequent ivcap ... commands (within the same CLI history/session). If you want the command outputs to show the full URNs (and avoid @… aliases), add --no-history.

To get more details about a specific service

% ivcap service get @1


        Name  llama-index-agent-runner
 Description  Executes queries or chats with LlamaIndex agents.

          ID  urn:ivcap:service:b35153c3-3f66-5ed1-9e33-c46949783575 (@1)
      Status  active
  Controller  urn:ivcap:schema.service.rest.1
      Policy  urn:ivcap:policy:ivcap.open.metadata
     Account  urn:ivcap:account:45a06508-5c3a-4678-8e6d-e6399bf27538
  Parameters  None

Follow this link for more details about the service command.

Jobs

A job is a specific instantiation of a service.

% ivcap job

Create and manage jobs

Usage:
  ivcap job [command]

Aliases:
  job, js, jobs

Available Commands:
  create      Create a new job
  get         Fetch details about a single job
  list        List existing jobs

Flags:
  -h, --help   help for job

To list all jobs initiated or visible to the user:

% ivcap job list --limit 2

 At Time  2 seconds ago (13 Oct 25 11:29 AEDT)
    Jobs  ┌────┬────────────────────────────────┬───────────┬──────────────┐
          │ ID │ SERVICE                        │ STATUS    │ REQUESTED AT │
          ├────┼────────────────────────────────┼───────────┼──────────────┤
          │ @1 │ Batch service example          │ succeeded │ 2 days ago   │
          │ @2 │ Gene Ontology (GO) Term Mapper │ succeeded │ 4 days ago   │
          └────┴────────────────────────────────┴───────────┴──────────────┘
  ... @3

To obtain the details of an existing job:

% ./ivcap job get @1

        Name  b-3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948-szje7stt

          ID  urn:ivcap:job:763e4b1d-26e4-4cd2-ba51-fb5a912a1e9c (@1)
      Status  succeeded
  Started At  2 days ago (10 Oct 25 13:29 AEDT)
 Finished At  2 days ago (10 Oct 25 13:29 AEDT)
     Service  urn:ivcap:service:3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948 (@2)
      Policy  urn:ivcap:policy:ivcap.base.service
     Account  urn:ivcap:account:45a06508-....

 Result-Type  application/vnd.ivcap.urn:sd:schema:batch-tester.1
      Result  {
                "$schema": "urn:sd:schema:batch-tester.1",
                "msg": "CPU consumption finished.",
                "run_time": 2.0046427249908447
              }

To crate a job from a service:

% ivcap job create -h
Create a new job by executing the service 'service-id' with the
input paramters defined in either a provided (json) file or a reference
to an aspect containing the parameter definitions. If the job definition is
provided through 'stdin' use '-' as the file name and also include the --format flag

Usage:
  ivcap job create [flags] service-id -f job-input|- -a aspect-urn --watch --stream

Flags:
  -a, --aspect string   URN of aspect containing job parameters
  -f, --file string     Path to job description file
      --format string   Format of input file [json, yaml] (default "json")
  -h, --help            help for create
      --stream          if set, print job related events to stdout
      --watch           if set, watch the job until it is finished

The --watch flag will block the command until the job has finished and then return the result.

% ivcap job create urn:ivcap:service:3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948 -f .../load_1.json --watch

        Name  b-3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948-oimafhg3

          ID  urn:ivcap:job:939f55f5-243b-49ef-8176-ee32eef966de (@1)
      Status  succeeded
  Started At  12 seconds ago (13 Oct 25 13:35 AEDT)
 Finished At  1 second ago (13 Oct 25 13:36 AEDT)
     Service  urn:ivcap:service:3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948 (@2)
      Policy  urn:ivcap:policy:ivcap.base.service
     Account  urn:ivcap:account:45a06508-5c3a-4678-8e6d-e6399bf27538

 Result-Type  application/vnd.ivcap.urn:sd:schema:batch-tester.1
      Result  {
                "$schema": "urn:sd:schema:batch-tester.1",
                "msg": "CPU consumption finished.",
                "run_time": 10.001116037368774
              }

In contrast, the --stream flag will also print out any events generated by the job during its execution. The individual events will be a mix of system related events (e.g. ivcap.job.status) and systemd specific ones (e.g. urn:ag-ui:schema:event.1).

% ivcap job create urn:ivcap:service:3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948 -f .../load_1.json --stream
---------
{
  "SeqID": "00007016",
  "EventID": "0199db6f-766e-7ebf-b113-96664880bcdb",
  "Type": "ivcap.job.status",
  "Schema": "urn:ivcap:schema:job.status.1",
  "Source": "b-3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948-gyfgm6rl",
  "Timestamp": "2025-10-13T02:38:59.141759565Z",
  "Data": {
    "job-urn": "urn:ivcap:job:a63971a8-4e99-460c-8e5e-d2b00a50e3f2",
    "status": "executing"
  }
}
---------
{
  "SeqID": "00007017",
  "EventID": "0199db6f-7721-7f05-8230-6c835856dc6d",
  "Type": "ivcap.job.event",
  "Schema": "urn:ag-ui:schema:event.1",
  "Source": "b-3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948-gyfgm6rl",
  "Timestamp": "2025-10-13T02:38:59.354310095Z",
  "Data": {
    "$schema": "urn:ag-ui:schema:event.1",
    "raw_event": "Consuming CPU for 10 seconds at 80%",
    "step_name": "consume_compute",
    "timestamp": 1760323139188,
    "type": "STEP_STARTED"
  }
}
---------
...
---------

        Name  b-3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948-gyfgm6rl

          ID  urn:ivcap:job:a63971a8-4e99-460c-8e5e-d2b00a50e3f2 (@1)
      Status  succeeded
  Started At  11 seconds ago (13 Oct 25 13:38 AEDT)
 Finished At  1 second ago (13 Oct 25 13:39 AEDT)
     Service  urn:ivcap:service:3678e5f1-8fb7-5ad6-b65b-8bd8c23c0948 (@2)
      Policy  urn:ivcap:policy:ivcap.base.service
     Account  urn:ivcap:account:45a06508-5c3a-4678-8e6d-e6399bf27538

 Result-Type  application/vnd.ivcap.urn:sd:schema:batch-tester.1
      Result  {
                "$schema": "urn:sd:schema:batch-tester.1",
                "msg": "CPU consumption finished.",
                "run_time": 10.020376205444336
              }

Artifacts

% ./ivcap artifact
Create and manage artifacts

Usage:
  ivcap artifact [command]

Aliases:
  artifact, a, artifacts

Available Commands:
  create      Create a new artifact
  download    Download the content associated with this artifact
  get         Fetch details about a single artifact
  list        List existing artifacts
  upload      Resume uploading artifact content

Flags:
  -h, --help   help for artifact

To check the details of the artifact created by the previously placed order:

% ivcap artifact get urn:ivcap:artifact:017ecae8...

         ID  urn:ivcap:artifact:017ecae8...
       Name  out.png
     Status  available
       Size  50855
  Mime-type  image/png
 Account ID  urn:ivcap:account:58d8e161...
   Metadata  ┌────┬─────────────────────────────────────────────┐
             │ @1 │ urn:ivcap:schema:artifact.1                 │
             │ @2 │ urn:ivcap:schema:artifact-usedBy-order.1    │
             │ @3 │ urn:example:schema:image-analysis:thumbnail │
             └────┴─────────────────────────────────────────────┘

To download the content associated with the artifact.

% ivcap artifact download urn:ivcap:artifact:017ecae8... -f /tmp/out.png
Successfully wrote 50855 bytes to /tmp/out.png

When artifact create uploads a local file named *.zip, *.tar, *.tar.gz or *.tgz it also adds a manifest aspect: an RO-Crate 1.2 JSON-LD document listing the files in the archive (schema urn:ivcap:schema:artifact.archive-manifest.1). Only the file name decides, so other ZIP-based formats such as .docx are not indexed. Use --without-manifest to skip it, or --manifest-schema to use another schema URN. --license records the license of the content in the manifest: an SPDX identifier such as CC-BY-4.0, a license URL, or undefined, the default. The manifest is a convenience: if an archive cannot be indexed, or the aspect cannot be added, a warning is printed and the upload still completes; run the same command again to retry the manifest, which never adds a second one. Content read from stdin is not indexed.

--chunk-size (bytes per upload request) must be at least 65536, or -1 to upload without chunking, which needs a known size and so does not work for stdin.

Follow this link for more details about the artifact command.

Collections

Collections allow you to organize and group artifacts and other resources.

% ivcap collection

Create and manage collections

Usage:
  ivcap collection [command]

Aliases:
  collection, c

Available Commands:
  create      Create a new collection
  get         Get a specific collection record
  list        List defined collections

Flags:
  -h, --help   help for collection

To create a new collection:

% ivcap collection create --name "My Research Data"
Collection 'My Research Data' created.

To list all collections:

% ivcap collection list

Follow this link for more details about the collection command.

DataFabric

The DataFabric allows you to query and manage aspects (metadata) associated with entities.

% ivcap datafabric

Query the datafabric and create and manage aspects within

Usage:
  ivcap datafabric [command]

Aliases:
  datafabric, df, aspect, as

Available Commands:
  add         Add aspect of a specific schema to an entity
  get         Get a specific aspect record
  query       Query the datafabric for any combination of entity, schema and time.
  retract     Retract a specific aspect record
  update      Update an aspect record for an entity and a specific schema

Flags:
  -h, --help   help for datafabric

To query the datafabric for aspects:

% ivcap datafabric query --entity urn:ivcap:entity:abc123 --schema my-schema:1

To add a new aspect:

% ivcap datafabric add --entity urn:ivcap:entity:abc123 --schema my-schema:1 -f aspect.json

Follow this link for more details about the datafabric command.

Nextflow

Nextflow integration provides commands for managing Nextflow-based pipeline services and jobs.

% ivcap nextflow

Commands for working with Nextflow-based services

Usage:
  ivcap nextflow [command]

Available Commands:
  create         Create a Nextflow service definition from a local archive
  job-get        Get status or results of a Nextflow job
  job-result     List or download files from a Nextflow job result artifact
  job-view       View Nextflow job execution report in a web browser
  list-jobs      List recent Nextflow jobs
  list-pipelines List Nextflow pipeline services
  retract        Retract the service aspect(s) created by 'nextflow create'
  run            Alias for 'ivcap job create'
  update         Update a Nextflow service definition from a local archive

Flags:
  -h, --help   help for nextflow

To list available Nextflow pipelines:

% ivcap nextflow list-pipelines

To run a Nextflow pipeline:

% ivcap nextflow run <service-id> -f input.json --watch

To view job results and reports:

% ivcap nextflow job-result <job-id>
% ivcap nextflow job-view <job-id>

Follow this link for more details about the nextflow command.

Queues

Queues allow you to manage message queues for asynchronous processing.

% ivcap queue

Queues are used to store messages in a sequential order. You can create, read, update, and delete queues using this command. You can also add and remove messages from queues.

Usage:
  ivcap queue [command]

Aliases:
  queue, q, queues

Available Commands:
  create      Create a new queue
  delete      Delete a queue
  dequeue     Dequeue messages from a queue
  enqueue     Enqueue a message to a queue
  get         Fetch details about a single queue
  list        List existing queues

Flags:
  -h, --help   help for queue

To create a queue:

% ivcap queue create my-queue
Queue 'my-queue' created.

To enqueue a message:

% ivcap queue enqueue my-queue "message content"

To dequeue messages:

% ivcap queue dequeue my-queue

Follow this link for more details about the queue command.

Secrets

Secrets allow you to store sensitive information securely.

% ivcap secret

Set and list secrets

Usage:
  ivcap secret [command]

Aliases:
  secret, secrets

Available Commands:
  get         Get single secret, show its expiry time and sha1 value
  list        List existing secrets
  set         Set a single secret value, overwrite if already exists

Flags:
  -h, --help   help for secret

To set a secret:

% ivcap secret set my-api-key "super-secret-value"
Secret 'my-api-key' set.

To list all secrets:

% ivcap secret list

To get a specific secret:

% ivcap secret get my-api-key

Follow this link for more details about the secret command.

Packages

The computation behind each service is encapsulated by one or more "packages" (aka Docker containers). This command supports managing them.

Upload packages (aka Docker containers)

ivcap package push -f alpine:3.20.1

 Pushing alpine:3.20.1 from local, may take multiple minutes depending on the size of the image ...
 40df18f632     4.21MB already exits
 092561eea8       1.45KB uploaded
 registry.kube-system.svc.cluster.local/0f0e3f57-80f7-4899-9b69-459af2efd789/alpine:3.20.1 pushed

Note: If the image is larger than 2GB we need to push it from a local registry instead of pusing it directly.

• Start a local registry

docker run -d -p 8080:5000 --name registry-2 registry:2

• Tag image

docker tag alpine:3.20.1 localhost:8080/alpine:3.20.1

• Push to local registry

docker push localhost:8080/alpine:3.20.1

• Then push from local registry to ivcap service

ivcap package push -f localhost:8080/alpine:3.20.1
 Pushing localhost:8080/alpine:3.20.1 from localhost:8080, may take multiple minutes depending on the size of the image ...
 a258b2a6b5     3.90MB uploaded
 092561eea8       1.45KB uploaded
 registry.kube-system.svc.cluster.local/0f0e3f57-80f7-4899-9b69-459af2efd789/alpine:3.20.1 pushed

List packages

ivcap package ls

registry.kube-system.svc.cluster.local/0f0e3f57-80f7-4899-9b69-459af2efd789/alpine:3.20.1
registry.kube-system.svc.cluster.local/0f0e3f57-80f7-4899-9b69-459af2efd789/cv_pipeline_v0_pm1:2024-03-27_16-48-57
registry.kube-system.svc.cluster.local/0f0e3f57-80f7-4899-9b69-459af2efd789/python:3.13.0

Follow this link for more details about the package command.

Genomes

The genome command looks up genome assemblies at NCBI Datasets, downloads their data packages and imports them into IVCAP. reports and download talk to NCBI directly, so they need no context and no login; import also needs a logged-in IVCAP context. It is built on the ivcap-ncbi-genome-download library.

Look up the assemblies behind an accession, either an assembly accession such as GCF_000001735.4 or a BioProject such as PRJNA10719 (which expands to its assemblies):

ivcap genome reports GCF_000001735.4

Download the data package of one genome:

ivcap genome download GCF_000001735.4 --include genome,gff3,seq-report -f TAIR10.1.zip

Import a genome into IVCAP instead of keeping a local file:

ivcap genome import GCF_000001735.4 --include genome,gff3,seq-report

• import takes the same package options as download. The package goes to a temporary file that is removed afterwards, and is uploaded as an artifact (named <ACCESSION>.zip unless --name is given).

• Two aspects are added to that artifact: the NCBI assembly report (schema urn:ivcap:schema:ncbi.assembly-data-report.1) and an RO-Crate 1.2 manifest of the files in the package (schema urn:ivcap:schema:artifact.archive-manifest.1). --report-schema and --manifest-schema override the schema URNs, and --policy sets the policy for the artifact and both aspects.

• The manifest records a license for the data. NCBI itself states none: it places no restrictions on use or distribution, but submitters may claim rights that it cannot assess. So by default the manifest links to NCBI's data usage policy, which is a pointer and not a license grant. --license states another one (an SPDX identifier, a license URL, or undefined).

• The artifact and both aspects get the open policies (urn:ivcap:policy:ivcap.open.artifact and urn:ivcap:policy:ivcap.open.metadata), because the imported data is public NCBI data. --policy gives all three another policy.

• import checks the accession, the license and the chunk size before it downloads anything, and it stops if NCBI answers the report and the download request with different assemblies.

• --output json|yaml prints the artifact URN and the two aspect IDs. If an aspect cannot be added after the upload, the error names the artifact.

• Running import again creates a new artifact.

• A download covers exactly one genome. Pass an assembly accession (GCF_... or GCA_...); a BioProject is rejected because it can name many genomes. Use ivcap genome reports to find the assembly first.

• --include chooses the files in the package: genome (genomic FASTA, the default), rna (transcripts), protein (amino acid sequences), cds (nucleotide coding sequences), gff3 or gtf (annotation), gbff (GenBank flat file), seq-report (per-sequence report), all (every type, on its own) or none (metadata only, on its own).

• --assembly-version decides which version is used. By default a versioned accession such as GCF_000001735.4 is used as given and an unversioned one means its current version. current (the same as latest) ignores the version in the accession and takes the current one. all selects every version, which download and import reject unless there is exactly one, so it is only useful with reports.

• --chromosomes limits the genome FASTA to the named chromosomes, or all; the names are passed to NCBI unchanged.

• Without -f the package is written to ./<ACCESSION>.zip. The command refuses to replace an existing file unless --force is given, and -f - writes the zip to stdout.

• --output json|yaml prints the result of a download (accession, file, size and the list of files in the package), or the full reports for reports. Each report follows the JSON Schema published with the library.

• NCBI limits request rates. An NCBI API key raises the limit: set NCBI_API_KEY or use --ncbi-api-key.

List the genomes that have been imported:

ivcap genome list

list shows one row per import that has an assembly report aspect: the accession from the report, the report aspect, and the artifact the aspect belongs to. The two URNs are shown as short @n references that other commands accept in place of the URN; --no-history shows the full URNs instead. --output json|yaml prints the same rows, with the organism and assembly name of each report, as genomes, plus next_page when there are more results, which --page takes to continue. It only talks to IVCAP, so it needs a context and login but no NCBI access.

Follow this link for more details about the genome command.

Agent / automation usage

This CLI is also frequently used by AI agents and automation.

• See AGENTS.md for agent operating rules.
• See skills/CONTEXT.md for agent-oriented usage patterns.
• Retrieve the version-matched agent context from the CLI (recommended):
  • ivcap --agent-context
  • ivcap --output json --agent-context
  • ivcap agent-context
• Skill docs are embedded into the CLI for offline, version-matched access:
  • ivcap skills list
  • ivcap skills search <query> (BM25-ranked, best match first)
  • ivcap skills show <skill-name>
  • (for programmatic usage) ivcap --output json skills list|search|show ...

MCP-Provisioned Skills (Resources + Prompts)

When running the built-in MCP server (ivcap mcp), the CLI also exposes the embedded skill playbooks via MCP Resources and a setup Prompt.

Recommended client system prompt

If you are building an MCP client (i.e. an agent/LLM host that connects to MCP servers), add the following instructions to your client’s system prompt:

Before answering any task:

1. Call resources/list on all connected MCP servers
2. Identify resources matching: *SKILL.md, *instructions*, *prompt*
3. Fetch and read matching resources via resources/read
4. Apply those instructions when completing the user's request

Resources

• skills://manifest — JSON list of available skills (name → skills://{name}/SKILL.md)
• skills://catalog.json — JSON catalog (metadata + SHA256; no markdown bodies)
• skills://CONTEXT.md — general agent best-practices for ivcap-cli
• skills://{name}/SKILL.md — the full markdown body of a specific skill

Prompt

• use-ivcap-best-practices — tells an agent to read skills://CONTEXT.md, then discover and load the relevant skills://{name}/SKILL.md docs for the current task.

Example JSON-RPC calls

You can send these messages to ivcap mcp in STDIO mode.

For example, this will initialize a session and list available resources:

ivcap mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}
EOF

List available skill resources:

{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}

Read the skills manifest:

{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"skills://manifest"}}

Read a specific skill body:

{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"skills://ivcap-job-create/SKILL.md"}}

Get the setup prompt:

{"jsonrpc":"2.0","id":4,"method":"prompts/get","params":{"name":"use-ivcap-best-practices"}}

Build from Source

Prerequisites

You will need the following installed:

• go version >= 1.22.5 (e.g. snap install go --classic)
• golangci-lint (e.g. go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest)
• gocritic (e.g. go install -v github.com/go-critic/go-critic/cmd/gocritic@latest; you may also need to add ~/go/bin to your PATH)
• staticcheck (e.g. go install honnef.co/go/tools/cmd/staticcheck@latest)
• gosec (e.g. go install github.com/securego/gosec/v2/cmd/gosec@latest)
• govulncheck (e.g. go install golang.org/x/vuln/cmd/govulncheck@latest)
• addlicense (e.g. go install github.com/nokia/addlicense@latest)

Install prerequisites

The prerequisite tools can be installed by running the make target:

make install-tools

Build & Install

To build and install from local source code, ensure you have the prerequisites and run:

make build
make install

If your Go paths are configured correctly, you should now have the ivcap command available in your shell.

To build and install without performing any code checks (implicitly done via make check) run:

make build-dangerously
make install-dangerously