Getting Started¶
This guide walks you through installing the IVCAP CLI, configuring a deployment context, and verifying your setup.
1. Install¶
macOS – Homebrew (recommended)¶
macOS / Linux – Download a pre-built binary¶
- Visit the Releases page
and download the archive for your platform (e.g.
ivcap_darwin_arm64.tar.gz). - Extract and move the binary onto your
$PATH:
Windows¶
Download the .zip for windows_amd64 from the
Releases page, extract
ivcap.exe, and add its directory to your PATH.
Build from source¶
Requires Go ≥ 1.21.
git clone https://github.com/ivcap-works/ivcap-cli.git
cd ivcap-cli
make build # produces ./ivcap
make install # installs to $GOPATH/bin
Verify the installation¶
2. Configure a deployment context¶
A context stores the URL of an IVCAP deployment and your credentials so you don't have to repeat them on every command.
Create a context¶
Example:
Tip
You can have multiple contexts (e.g. develop, staging, prod) and
switch between them with ivcap context set <name>.
List and switch contexts¶
ivcap context list # show all configured contexts
ivcap context set myivcap # make 'myivcap' the active context
ivcap context get # show details of the active context
3. Log in¶
Once a context is active, authenticate to obtain an access token:
This opens a browser window for your identity provider's login flow. After successful authentication the token is stored locally and refreshed automatically.
Headless / non-interactive login (CI, agents)¶
If you already have a token (e.g. from a CI secret), skip the browser flow:
or pass it inline:
4. Verify your connection¶
A successful response returns a JSON array of available services. If you see
an authentication error, re-run ivcap context login.
5. Submit your first job¶
# Find a service to run
ivcap service list --limit 10
# Inspect its parameters
ivcap service get urn:ivcap:service:<uuid>
# Create a job (params can be JSON inline or from a file)
ivcap job create urn:ivcap:service:<uuid> \
--parameter key=value \
--watch # stream events until the job finishes
# Retrieve the job result
ivcap job get urn:ivcap:job:<uuid>
Next steps¶
- Browse the Core concepts & commands for a full list of commands.
- Set up the MCP server to let AI agents interact with IVCAP.
- Read the agent skills for best-practice workflow patterns.