@seiva-ai/cli

Command-line tool for syncing Seiva apps and Python tools between your local IDE and the Seiva platform — git-style clone, status, pull, push, build, publish.

Pairs with @seiva-ai/mcp-server, the MCP server used by IDE coding agents (Claude Code, Codex, Cursor, Antigravity). The MCP server depends on this package; you only need to install the CLI directly if you want to drive sync from a shell instead of from your agent.

Install

npm install -g @seiva-ai/cli
seiva --help

Node 18.17+ required.

Login

seiva login
# Seiva URL: https://platform.seiva.ai
# Seiva API key: seiva_...

Writes ~/.seiva/config.json with mode 0600. Generate your API key under /api-keys in the platform UI — must be workspace-scoped (created by a user logged into a workspace). Partnership-scoped keys cannot acquire EditLock and will reject push.

The CLI also reads SEIVA_URL and SEIVA_API_KEY from env vars (env wins over the config file).

Apps workflow

seiva clone <app-id> --dir my-app
cd my-app && npm install        # IDE intellisense only; real build runs server-side
# edit with your IDE / agent
seiva status                    # local vs manifest (added / modified / deleted)
seiva push -m "feat: ..."       # acquires lock, batches with expected_sha256, releases lock
seiva pull                      # remote → local; refuses dirty tree without --force
seiva build                     # POST /build; returns preview_url
seiva publish -m "v1.2"         # snapshot working tree as a new published version

Tools workflow (Python tools)

seiva tool clone <tool-id> --dir my-tool
cd my-tool
# files: main.py, input_schema.json, tool.json, README.md
seiva tool status
seiva tool pull [--force]
seiva tool push [--force] [-m "msg"]

Tools don't have a build step — push is publish.

Concurrency model

• Optimistic concurrency — every file has a content_sha256. push sends expected_sha256 per file; the server returns 409 Conflict with current_sha256 and current_content on drift. CLI prints the conflicting paths and recommends seiva pull.
• Edit lock — push acquires a 2-minute EditLock scoped {:app, app_id} (or {:tool, tool_id}), heartbeats every 30 s, releases on SIGINT/SIGTERM/SIGHUP. Lock conflict returns 409 with holder_name and expires_at.
• Working tree filter — node_modules/, package.json, package-lock.json, .gitignore, tsconfig.json and other IDE-only scaffolding (see lib/dev_tooling.js) are never pushed or pulled. Idempotent regeneration on clone.

Programmatic API

For embedding (used by @seiva-ai/mcp-server):

import { findCheckoutRoot, readManifest, scanWorkingTree } from "@seiva-ai/cli/manifest";
import { findToolCheckoutRoot, readToolManifest } from "@seiva-ai/cli/tool_manifest";
import { computeDigest } from "@seiva-ai/cli/digest";

The bin can be spawned directly:

import { createRequire } from "node:module";
const cliBin = createRequire(import.meta.url).resolve("@seiva-ai/cli/bin/seiva.js");
spawn(process.execPath, [cliBin, "status"]);

License

MIT — see LICENSE.