Kodara CLI

@kodara-agent/cli manages Kodara agent definitions as small, versioned Markdown folders. The installed executable is kodara.

Install and authorize

npm install --global @kodara-agent/cli
kodara login

Login opens a one-time browser approval page. Only a current Kodara super admin can approve access. The resulting revocable token is stored in the operating system's user configuration directory with owner-only file permissions.

Use --api-url http://localhost:3001 or KODARA_API_URL for a non-production API. An explicit flag wins over the environment, saved login URL, and production default.

Find and pull an agent

kodara customers search "Acme"
kodara agents list --customer <organization-id>
kodara agents pull <agent-id>

To enumerate agents across all accessible customers, use the global list. It supports the active-agent and due-for-improvement filters used by the operator loop:

kodara agents list --active --needs-update --order oldest --limit 100 --json

Pull writes kodara-workspace/<customer>/<agent>/ with index.md, linked rubric files, situation-grouped style examples, evals/*.md, pending/Unprocessable feedback, and .kodara/manifest.json. Definition files and feedback are independently hashed. A concise AGENTS.md and project-local .agents/skills/rubric-editing/ skill are created for coding agents. Do not edit the manifest or feedback contents.

Explicitly download recent learning evidence when needed:

kodara agents learning pull ./kodara-workspace/acme/coach

This writes at most 100 recent conversations and 100 messages per conversation under local-only learning/. A normal agent pull never downloads, deletes, or publishes that tree. Use --conversations, --messages, or --force to lower bounds or intentionally replace a modified export.

Publish and restore

kodara agents push ./kodara-workspace/acme/coach --message "Clarify identity"
kodara agents validate ./kodara-workspace/acme/coach
kodara agents diff ./kodara-workspace/acme/coach
kodara agents eval ./kodara-workspace/acme/coach --limit 20
kodara agents eval ./kodara-workspace/acme/coach --agent-version 4 --limit 20
kodara agents versions ./kodara-workspace/acme/coach
kodara agents rollback 2 ./kodara-workspace/acme/coach --message "Restore tested behavior"

diff compares versioned files with the exact pulled immutable base. eval runs up to 20 regression cases server-side against either the current unpublished local snapshot or a selected published version. It uses the editable coach-specific evals/evaluator.md, prints progress and bounded results, creates no chat data or agent version, and never publishes.

Every content-changing push and rollback creates a new immutable server version immediately. Push uses the pulled base version, canonical snapshot hash, and validated .kodara/improvement.json, so stale work is rejected instead of overwriting a newer publish. Pull refuses to overwrite local edits unless --force is explicit. --force replaces the local Markdown map, including removing untracked Markdown absent from the server, but never bypasses symlink/path safety, manifest identity, or the workspace's pinned API origin.

To apply pending feedback, make the corresponding surgical definition edit and move its unchanged UUID file from feedback/pending/ to feedback/processed/. The CLI never sends feedback Markdown as runtime instructions. The server links the selected feedback to the immutable version in the same transaction.

When feedback cannot be safely applied, move its unchanged file from feedback/pending/ to feedback/unprocessable/ and push it separately without --message. That review-only push creates no agent version. The item remains in future pulls and can later move from feedback/unprocessable/ to feedback/processed/ with the definition change that resolves it.

Regression evals live at evals/<source-user-message-uuid>.md, one file per source prompt. They are versioned with the definition but are never readable by Agent V5 at runtime. Run kodara agents validate <agent-directory> before publishing; malformed evals report the exact file and contract failure without making an API request.

Add general or message-linked feedback with:

kodara feedback add --agent <agent-id> --type <style|knowledge|issue> --message "..." [--message-id <id>]

kodara logout revokes the server token before deleting the local credential. If revocation cannot be confirmed, the credential remains so logout can be retried.

After a rollback, pull the agent again to synchronize the restored files and new version into the local manifest.

Profile memory

kodara memory copy --agent <agent-id> --profile <profile-id>

This server-side command strictly reads and copies the selected profile-agent pair's existing memory files into the new private virtual-folder format. Memory contents never pass through the CLI; a source database failure fails the command, and the legacy memory writer remains authoritative during the baseline.

After initialization, explicitly edit that profile's virtual memory with a separate workspace:

kodara memory pull --agent <agent-id> --profile <profile-id>
kodara memory push ./kodara-workspace/acme/memory/coach/jamie --message "Update current goal"

The memory manifest is profile-scoped and cannot be used by kodara agents push. The API rechecks that the selected profile belongs to the agent's organization or has explicit access before returning or publishing any memory files.