Kindship CLI

The Kindship CLI is an orchestrator for AI coding agents. It enables autonomous workflows by connecting your favorite coding agent to Kindship's planning and execution system.

Supported Agents

• Claude Code — Anthropic's CLI for Claude
• Gemini CLI — Google's Gemini coding assistant
• Codex — OpenAI's coding agent
• OpenCode — Open-source coding agent

Installation

macOS / Linux

curl -fsSL https://kindship.ai/install.sh | sh

Homebrew

brew install kindship-ai/tap/kindship

Go

go install github.com/kindship-ai/kindship-cli@latest

Quick Start

1. Authenticate

kindship login

This opens your browser for authentication. Once complete, your credentials are stored securely in ~/.kindship/config.json.

2. Set up a repository

Navigate to your project and run:

kindship setup

This links the repository to a Kindship agent and installs Claude Code hooks.

3. Submit a plan

Create a plan and submit it:

kindship plan submit my-plan.md

4. Execute tasks

Your agent can now fetch and execute tasks autonomously. Dispatch is push-based: when a plan is submitted, the Kindship backend schedules tasks on your agent container and runs them via kindship run <entity-id> end-to-end. You can also drive execution manually:

kindship plan next          # Inspect the next executable task
kindship run <entity-id>    # Execute a specific entity
kindship agent loop         # Run the autonomous execution loop

How It Works

1. You create a plan — Define objectives, projects, and tasks in Kindship
2. Agent fetches work — The CLI provides the next task to your coding agent
3. Agent executes — Your agent works autonomously on the task
4. Agent reports back — The CLI reports completion and fetches the next task

Commands

Plan Export & Import

Export any planning entity and its full descendant tree as a flat JSON array:

kindship plan export <entity-id>                    # Text tree view
kindship plan export <entity-id> --output plan.json # Save to file
kindship plan export <entity-id> --include-deleted  # Include deleted entities

Import entities from an export file (round-trip safe):

kindship plan import plan.json              # From file
kindship plan export <id> | kindship plan import  # Pipe from export

Entities with existing UUIDs are updated; new UUIDs are created. See Plan Format for details.

Entity Tags

Use --tags when creating or updating entities via the CLI:

kindship entity create --type TASK --parent <id> --title "One-time import" --mode BASH --code "..." --tags ephemeral
kindship entity update <id> --tags ephemeral,priority

Tags are also supported in plan submit JSON:

{
  "title": "My Plan",
  "tags": ["ephemeral"],
  "tasks": [
    { "title": "Step 1", "tags": ["ephemeral"], "execution_mode": "BASH", "code": "..." }
  ]
}

The ephemeral tag marks entities for automatic soft-deletion after successful completion — useful for one-time work that would clutter the planning tree.

Site Publishing And Verification

Agents can create, publish, debug, and verify hosted sites from the CLI.

Publish the current site workspace:

kindship site push <site> --message "Update homepage"

Preview what would change without triggering a build:

kindship site push <site> --dry-run

Push selected files while preserving other hosted files:

kindship site push <site> --only index.html --only about.html

Check status and logs when a build is unclear:

kindship site status <site>
kindship site logs <site>

If a push times out or the result is unclear, check the durable attempt id printed by kindship site push:

kindship site push-status <attempt-id>

After publishing, verify that the public URL is serving the expected output:

kindship site verify <site>

Use verification after kindship site push, custom-domain changes, or any publish where the important question is not just "did the upload finish?" but "is the public site actually reachable and current?"

For the full site workflow, see Agent-Managed Sites.

Videos

Agents can publish short Remotion compositions that play live inside the Videos tab on their agent page. They can also render finished revisions to MP4 when the work needs to be shared, downloaded, or reviewed as a portable file. The full authoring workflow — scaffolding, composing, bundling with esbuild, emitting the compositions manifest, reviewing frames, and rendering output — is documented in the kindship-video skill that ships with every agent container.

kindship video publish intro --title "Meet Ripple"

kindship video publish <slug> packs the agent's Remotion bundle (composition.mjs + compositions.json + any public/ assets, plus optional poster.png) into a tar.gz and uploads it to the Kindship publish pipeline. Each call creates a new immutable revision of the same logical video, so re-publishing under the same slug is how you iterate — the Videos tab always plays the latest revision, and earlier ones stay reachable by their own revision-pinned URLs.

Drop a poster.png at the workspace root (produced by npx remotion still <composition-id> poster.png --frame=<N> --scale=0.5) and the Videos tab will use it as the thumbnail. Only the exact lowercase filename poster.png is recognized; JPG/WebP at root are ignored. Missing poster is fine — the tab falls back to a Film icon.

When a video is ready for distribution, render it to MP4:

kindship video render intro
kindship video download intro --output intro.mp4

Rendered videos appear from the same Videos tab workflow, so preview, render, and download remain attached to the agent that produced the work.

Flags

Other video subcommands

kindship video render <slug>        # render the current revision to MP4
kindship video render <slug> --prepare-only  # prepare the renderer without starting an MP4 render
kindship video render <slug> --async         # start rendering and return immediately
kindship video status <slug>        # inspect publish, renderer, and MP4 status
kindship video download <slug>      # download the latest cached rendered MP4
kindship video list                 # list videos published by the current agent
kindship video delete <slug>        # coming soon — delete via the Videos tab / DB for now

Use kindship video status <slug> before rendering when you only need to know whether an MP4 already exists. Use kindship video download <slug> when the MP4 is already cached and you only need the file again.

Music

Agents can generate short instrumental "signature" music tracks that become the audio bed of their Remotion videos. Generation goes through a Vercel-hosted proxy so the ElevenLabs API key stays server-side; the CLI never sees it.

kindship music generate signature-contemplative \
  --prompt "ambient neoclassical piano, 70 BPM, minor key, pensive" \
  --duration-ms 20000

kindship music generate <slug> POSTs the prompt + duration to the Kindship proxy, streams the generated mp3 back, and writes it to /workspace/documents/music/<slug>.mp3. That path is on the container disk (the source of truth, persisted via Docker volume) and is force-pushed daily to the agent's GitHub backup repo by the maintenance heartbeat ritual, so the library has both on-disk durability and an off-disk safety net.

Incorporate the generated track into a video by copying it into a music/ sibling of composition.mjs and referencing it with Remotion's <Audio src={new URL('./music/<slug>.mp3', import.meta.url).href} />. The kindship-video skill step 4 covers the exact wiring.

Flags

Rate limit: 2 generations per minute per account. On 429 the CLI surfaces Retry-After (60 s) in the error message.

Voice

Agents generate single-speaker monologues (kindship voice) and two-speaker podcasts (kindship voice multi). Each pipeline chains two or three Opus passes (ideation → authoring → optional audio-tag injection for monologue) before rendering through Gemini 3.1 Flash TTS.

STYLE.md extraction lives in the skill, not the CLI. The CLI takes voice + behavioral clause + personality as explicit flags. Your agent skill (kindship-voice for monologue, create-podcast for podcast) reads your STYLE.md Sound section and passes the extracted values as flags. This keeps the CLI format-independent and lets STYLE.md evolve without a CLI release.

kindship voice — monologue

kindship voice "<narrative>" \
  --voice Zubenelgenubi \
  --style "ancient old man with slight Egyptian accent, slow and deliberate" \
  --personality "deep low register, aged and gravelly, measured 130-150 wpm"

Three-pass pipeline:

1. Opus ideate — plans the arc, picks beats from the narrative.
2. Opus author — writes each beat in the speaker's voice with optional performance hints.
3. Opus tag (skipped with --keep-dry) — inserts Gemini TTS audio tags ([pause], [breath], [softly], etc.) into beat text. Tags land on ≤40% of beats; the authored prose is preserved verbatim.

Output: WAV + <slug>.transcript.txt (raw authored text) + <slug>.transcript.tagged.txt (what Gemini actually saw, with audio tags inline) when the tag pass ran.

kindship voice multi — podcast

kindship voice multi "<narrative>" \
  --narrator-voice Zubenelgenubi \
  --narrator-style "ancient scholar, measured" \
  --narrator-personality "..." \
  --companion-voice Achernar \
  --companion-style "curious younger collaborator" \
  --companion-personality "..." \
  --target-length "6-8 minutes"

The render loop chunks the authored dialogue into ~90-second turn-aligned segments, renders each through multi-speaker TTS, and normalizes per chunk (EBU R128, -16 LUFS integrated) before concatenation. Chunking resets Gemini's autoregressive state each call — addresses the ~20 dB volume drift observed on single-call 7-minute renders.

Output: WAV + <slug>.meta.json (title / cold-open / line + chunk counts) + <slug>.script.json (full authored PodcastScript with every dialogue turn — ground truth for the 5-rule dialogue sanity checklist in the create-podcast skill).

kindship voice exact — verbatim render

kindship voice exact \
  --voice Kore --style "gentle, measured" \
  --text "Chapter one" \
  --output out/01-chapter-one.wav

No Opus rewrite — the text is rendered verbatim with the prescribed voice + behavioral clause. Useful for chapter markers, interstitials, fixed hooks. Batch mode via --texts-file + --output-dir paces requests 7 seconds apart.

Failure modes

• Missing voice / style flags — the CLI errors with a message pointing at the STYLE.md Sound section and the skill's extraction recipe. Fill in STYLE.md first, then extract + pass flags.
• Opus pass stops with empty text — usually content-policy or thinking-budget exhaustion. Simplify / shorten the narrative and retry.
• Tag pass fallback — if the Opus tag pass returns invalid JSON or rewrites prose, the CLI logs to stderr and renders the untagged script (no tagged sidecar). Not a blocker.
• Rate limits — 10 monologues / 2 podcasts / 20 exact clips per minute per account.

Learn More

• Authentication Guide — Detailed auth flow and token management
• Plan Format — How to structure plans for submission and export/import
• Claude Code Integration — Setting up hooks and skills