README
¶
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
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.gzfrom a list of sources (text/base64/url/artifact), upload it as an artifact, validateivcap-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 and set access to various IVCAP deployments
datafabric Query the datafabric and create and manage aspects within
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
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...
Follow this link for more details about the context command.
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@1are local history aliases for the actual resource URNs returned by the platform. You can typically reference@1in subsequentivcap ...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
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.
Agent / automation usage
This CLI is also frequently used by AI agents and automation.
- See
AGENTS.mdfor agent operating rules. - See
skills/CONTEXT.mdfor agent-oriented usage patterns. - Retrieve the version-matched agent context from the CLI (recommended):
ivcap --agent-contextivcap --output json --agent-contextivcap agent-context
- Skill docs are embedded into the CLI for offline, version-matched access:
ivcap skills listivcap skills show <skill-name>- (for programmatic usage)
ivcap --output json skills list|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:
- Call
resources/liston all connected MCP servers- Identify resources matching:
*SKILL.md,*instructions*,*prompt*- Fetch and read matching resources via
resources/read- 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 forivcap-cliskills://{name}/SKILL.md— the full markdown body of a specific skill
Prompt
use-ivcap-best-practices— tells an agent to readskills://CONTEXT.md, then discover and load the relevantskills://{name}/SKILL.mddocs 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/binto yourPATH) - 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
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
adapter
Program to create, update & delete aspect schemas in cayp Adapted from https://github.com/maxott/cayp-cli/blob/main/pkg/adapter/adapter.go
|
Program to create, update & delete aspect schemas in cayp Adapted from https://github.com/maxott/cayp-cli/blob/main/pkg/adapter/adapter.go |
|
nextflow
Package nextflow contains reusable logic for working with Nextflow-based services:
|
Package nextflow contains reusable logic for working with Nextflow-based services: |