Skip to content

ptkl kortex

Interactive AI coding assistant, plus non-interactive management of Kortex agents, knowledge bases, documents, conversations, usage and billing.

Overview

ptkl kortex has two faces:

  • Bare invocation (ptkl kortex [prompt...]) launches an interactive TUI chat session with a Kortex agent — the platform's built-in AI assistant. This is unaffected by the management subtree below.
  • Management subcommands (agent, kb, doc, conversation, usage, tier, top-up) are non-interactive and map onto the SDK Kortex client (@ptkl/sdk/beta).

See also Kortex — AI Integration for how Forge apps register tools/context that the assistant can call into.

Interactive chat

ptkl kortex [prompt...] [-a <uuid>] [-c <uuid>] [--cloud]
Option Description
[prompt...] Optional initial prompt to seed the conversation
-a, --agent <uuid> Agent UUID to use (default: last used agent, or protokol-bot)
-c, --conversation <uuid> Resume a conversation (local or cloud)
--cloud Save the conversation on the platform (default: local only) 
# Launch the TUI with the default agent
ptkl kortex

# Seed an initial prompt and save the conversation on the platform
ptkl kortex "explain this workflow error" --cloud

# Resume a saved conversation with a specific agent
ptkl kortex --agent 3fae1c2e-... --conversation 9c21ab4f-...

Note

-a/--agent, -c/--conversation, and --cloud are reserved by the parent kortex command for the interactive chat. No subcommand below declares those names — the knowledge base search subcommand uses --agent-uuid instead (see kb search).

Subcommands

Subcommand Description
agent list List Kortex agents
agent get Get a Kortex agent by UUID
agent create Create a Kortex agent
agent update Update a Kortex agent
agent delete Delete a Kortex agent
kb list List Kortex knowledge bases
kb create Create a Kortex knowledge base
kb update Update a Kortex knowledge base
kb delete Delete a Kortex knowledge base
kb search RAG search over the knowledge bases attached to an agent
doc list List documents in a knowledge base
doc upload Upload a document to a knowledge base
doc get Get a document by UUID
doc delete Delete a document
doc retry Retry processing a failed document
conversation list List Kortex conversations
conversation get Get a Kortex conversation by UUID
conversation delete Delete a Kortex conversation
usage Get aggregated Kortex usage for the project, or a single user with --user
tier Get the current project's Kortex tier
top-up Top up credits for a Kortex user-access record

Agent

ptkl kortex agent list

List Kortex agents.

ptkl kortex agent list [-p <page>] [-l <limit>]

ptkl kortex agent list --limit 20

ptkl kortex agent get

Get a Kortex agent by UUID.

ptkl kortex agent get -u <uuid>

ptkl kortex agent get --uuid 3fae1c2e-...

ptkl kortex agent create

Create a Kortex agent.

ptkl kortex agent create -d <json>
Option Description
-d, --data <json> Agent payload as a JSON string (name, description, system_prompt, knowledge_bases, rag_config, llm_settings, model_tier) (required) 
ptkl kortex agent create --data '{"name":"Support Bot","system_prompt":"You help users with billing questions.","model_tier":"standard"}'

ptkl kortex agent update

Update a Kortex agent.

ptkl kortex agent update -u <uuid> -d <json>

ptkl kortex agent update --uuid 3fae1c2e-... --data '{"system_prompt":"Updated instructions..."}'

ptkl kortex agent delete

Delete a Kortex agent.

ptkl kortex agent delete -u <uuid>

ptkl kortex agent delete --uuid 3fae1c2e-...

Knowledge base

ptkl kortex kb list

List Kortex knowledge bases.

ptkl kortex kb list [-p <page>] [-l <limit>]

ptkl kortex kb list

ptkl kortex kb create

Create a Kortex knowledge base.

ptkl kortex kb create -d <json>
Option Description
-d, --data <json> Knowledge base payload as a JSON string (name, description, chunking_strategy) (required) 
ptkl kortex kb create --data '{"name":"Product Docs","chunking_strategy":"semantic"}'

ptkl kortex kb update

Update a Kortex knowledge base.

ptkl kortex kb update -u <uuid> -d <json>

ptkl kortex kb update --uuid 9c21ab4f-... --data '{"description":"Updated description"}'

ptkl kortex kb delete

Delete a Kortex knowledge base.

ptkl kortex kb delete -u <uuid>

ptkl kortex kb delete --uuid 9c21ab4f-...

RAG search over the knowledge bases attached to an agent.

ptkl kortex kb search <query> --agent-uuid <uuid> [-k <n>]
Option Description
<query> Search query (required)
--agent-uuid <uuid> Agent UUID — knowledge bases are derived from the agent (required)
-k, --top-k <n> Number of chunks to return (server-clamped 1-10) 
ptkl kortex kb search "refund policy" --agent-uuid 3fae1c2e-... --top-k 5

Document

ptkl kortex doc list

List documents in a knowledge base.

ptkl kortex doc list -k <uuid> [-p <page>] [-l <limit>]

ptkl kortex doc list --kb 9c21ab4f-...

ptkl kortex doc upload

Upload a document to a knowledge base.

ptkl kortex doc upload -k <uuid> --file <path> [-n <name>]
Option Description
-k, --kb <uuid> Knowledge base UUID (required)
--file <path> Path to the file to upload (required)
-n, --name <name> Override the uploaded file name (default: the file's basename) 
ptkl kortex doc upload --kb 9c21ab4f-... --file ./refund-policy.pdf

ptkl kortex doc get

Get a document by UUID.

ptkl kortex doc get -k <uuid> -u <uuid>

ptkl kortex doc get --kb 9c21ab4f-... --uuid 7b1e4a2d-...

ptkl kortex doc delete

Delete a document.

ptkl kortex doc delete -k <uuid> -u <uuid>

ptkl kortex doc delete --kb 9c21ab4f-... --uuid 7b1e4a2d-...

ptkl kortex doc retry

Retry processing a failed document.

ptkl kortex doc retry -k <uuid> -u <uuid>

ptkl kortex doc retry --kb 9c21ab4f-... --uuid 7b1e4a2d-...

Conversation

ptkl kortex conversation list

List Kortex conversations.

ptkl kortex conversation list [--all-users] [--archived] [-p <page>] [-l <limit>]
Option Description
--all-users Include conversations from all users (admin)
--archived Include archived conversations 
ptkl kortex conversation list --all-users --limit 50

ptkl kortex conversation get

Get a Kortex conversation by UUID.

ptkl kortex conversation get -u <uuid>

ptkl kortex conversation get --uuid 9c21ab4f-...

ptkl kortex conversation delete

Delete a Kortex conversation.

ptkl kortex conversation delete -u <uuid>

ptkl kortex conversation delete --uuid 9c21ab4f-...

Usage, tier & top-up

ptkl kortex usage

Get aggregated Kortex usage for the current project (admin), or a single user with --user.

ptkl kortex usage [-u <uuid>] [-m <yyyy-mm>] [--breakdown] [-p <page>] [-l <limit>]
Option Description
-u, --user <uuid> User-access UUID to scope usage to
-m, --month <yyyy-mm> Month to scope usage to
--breakdown With --user, return the monthly usage breakdown instead of the current month
-p, --page <page> Page number
-l, --limit <limit> Page size 
# Project-wide usage for a month
ptkl kortex usage --month 2026-07

# A single user's monthly breakdown
ptkl kortex usage --user 7b1e4a2d-... --breakdown

ptkl kortex tier

Get the current project's Kortex tier.

ptkl kortex tier

ptkl kortex top-up

Top up credits for a Kortex user-access record.

ptkl kortex top-up -u <uuid> --amount <amount> [-r <reason>]
Option Description
-u, --uuid <uuid> User-access UUID to top up (required)
--amount <amount> Amount of credits to add (required)
-r, --reason <reason> Reason for the top-up 
ptkl kortex top-up --uuid 7b1e4a2d-... --amount 500 --reason "manual grant"

Typical Workflow

# 1. Create a knowledge base and upload docs
ptkl kortex kb create --data '{"name":"Product Docs"}'
ptkl kortex doc upload --kb <kb-uuid> --file ./refund-policy.pdf

# 2. Create an agent wired to that knowledge base
ptkl kortex agent create --data '{"name":"Support Bot","knowledge_bases":["<kb-uuid>"]}'

# 3. Search the knowledge base directly, or chat with the agent
ptkl kortex kb search "refund policy" --agent-uuid <agent-uuid>
ptkl kortex --agent <agent-uuid>

# 4. Check usage and top up if needed
ptkl kortex usage --month 2026-07
ptkl kortex top-up --uuid <user-access-uuid> --amount 500

See Also