CLI

Work with Kival from the command line and use structured commands in scripts and agent workflows.

The Kival CLI is a first-class programmatic interface for shells, scripts, and tool-using agents. It exposes the same shared knowledge model as the HTTP API without requiring an application dependency.

Installation

The kival CLI is distributed with official Kival releases. Follow the installation instructions to install kivalup and Kival on a supported platform.

Configure a connection

Point the CLI at a Kival server and provide an API key:

export KIVAL_URL="https://kival.example"
export KIVAL_API_KEY="..."

Use kival whoami to verify the authenticated identity and effective API-key context before automating mutations.

Work with Kival from the shell

The CLI covers workspace discovery, objects and versions, search, relationships and graph operations, attachments, commentary, events, access management, and supported administration.

Use command help as the exact reference for flags and subcommands; the CLI metadata is kept alongside the implementation and is the least ambiguous source for command syntax.

Prefer JSON for automation

Human-readable text is the default, while --output json provides structured output for scripts and agents. --fields can project selected fields when a consumer only needs part of a result.

For larger mutations, commands can accept structured JSON from a file or standard input:

kival objects create <WORKSPACE_ID> --input object.json
cat object.json | kival objects create <WORKSPACE_ID> --input -

Where supported, object bodies can also come from files or stdin. Unknown structured-input fields are rejected instead of silently ignored.

Treat server semantics as canonical

CLI pagination, conflicts, rate limits, authorization, and error behavior come from the same HTTP API used by the SDKs. Do not decode cursors or invent retry behavior around mutations; follow the contracts described in API.

The key also needs the scopes and workspace delegation required by the command. See Agent access for credential boundaries.

When the CLI fits

The CLI is a good boundary when you want to:

  • explore Kival from a shell;

  • compose Kival with existing command-line tools;

  • give an agent a discoverable executable interface;

  • write small scripts without adding an SDK dependency.

For a long-running service or application, use the HTTP API or an official SDK instead of managing subprocesses and parsing command output.