kctl-claw 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. kctl_claw-0.2.0/.gitignore +33 -0
  2. kctl_claw-0.2.0/PKG-INFO +19 -0
  3. kctl_claw-0.2.0/README.md +205 -0
  4. kctl_claw-0.2.0/pyproject.toml +47 -0
  5. kctl_claw-0.2.0/skills/openclaw-admin/SKILL.md +309 -0
  6. kctl_claw-0.2.0/src/kctl_claw/__init__.py +3 -0
  7. kctl_claw-0.2.0/src/kctl_claw/__main__.py +5 -0
  8. kctl_claw-0.2.0/src/kctl_claw/cli.py +173 -0
  9. kctl_claw-0.2.0/src/kctl_claw/commands/__init__.py +0 -0
  10. kctl_claw-0.2.0/src/kctl_claw/commands/agents.py +323 -0
  11. kctl_claw-0.2.0/src/kctl_claw/commands/agents_test.py +264 -0
  12. kctl_claw-0.2.0/src/kctl_claw/commands/ai.py +122 -0
  13. kctl_claw-0.2.0/src/kctl_claw/commands/aliases.py +63 -0
  14. kctl_claw-0.2.0/src/kctl_claw/commands/backup.py +112 -0
  15. kctl_claw-0.2.0/src/kctl_claw/commands/config_cmd.py +248 -0
  16. kctl_claw-0.2.0/src/kctl_claw/commands/config_drift.py +169 -0
  17. kctl_claw-0.2.0/src/kctl_claw/commands/cron.py +338 -0
  18. kctl_claw-0.2.0/src/kctl_claw/commands/cron_debug.py +220 -0
  19. kctl_claw-0.2.0/src/kctl_claw/commands/deploy.py +217 -0
  20. kctl_claw-0.2.0/src/kctl_claw/commands/docker_cmd.py +198 -0
  21. kctl_claw-0.2.0/src/kctl_claw/commands/doctor_cmd.py +222 -0
  22. kctl_claw-0.2.0/src/kctl_claw/commands/env.py +154 -0
  23. kctl_claw-0.2.0/src/kctl_claw/commands/health.py +94 -0
  24. kctl_claw-0.2.0/src/kctl_claw/commands/lint_cmd.py +267 -0
  25. kctl_claw-0.2.0/src/kctl_claw/commands/logs.py +71 -0
  26. kctl_claw-0.2.0/src/kctl_claw/commands/mcp.py +322 -0
  27. kctl_claw-0.2.0/src/kctl_claw/commands/mcp_test.py +250 -0
  28. kctl_claw-0.2.0/src/kctl_claw/commands/memory.py +359 -0
  29. kctl_claw-0.2.0/src/kctl_claw/commands/monitor_cmd.py +192 -0
  30. kctl_claw-0.2.0/src/kctl_claw/commands/pipeline.py +200 -0
  31. kctl_claw-0.2.0/src/kctl_claw/commands/prompts.py +286 -0
  32. kctl_claw-0.2.0/src/kctl_claw/commands/security.py +169 -0
  33. kctl_claw-0.2.0/src/kctl_claw/commands/skill_cmd.py +76 -0
  34. kctl_claw-0.2.0/src/kctl_claw/commands/skills.py +144 -0
  35. kctl_claw-0.2.0/src/kctl_claw/commands/skills_test.py +269 -0
  36. kctl_claw-0.2.0/src/kctl_claw/commands/status.py +78 -0
  37. kctl_claw-0.2.0/src/kctl_claw/commands/telegram.py +235 -0
  38. kctl_claw-0.2.0/src/kctl_claw/commands/test_cmd.py +213 -0
  39. kctl_claw-0.2.0/src/kctl_claw/commands/trading.py +269 -0
  40. kctl_claw-0.2.0/src/kctl_claw/core/__init__.py +0 -0
  41. kctl_claw-0.2.0/src/kctl_claw/core/callbacks.py +74 -0
  42. kctl_claw-0.2.0/src/kctl_claw/core/config.py +118 -0
  43. kctl_claw-0.2.0/src/kctl_claw/core/config_manager.py +123 -0
  44. kctl_claw-0.2.0/src/kctl_claw/core/docker_client.py +191 -0
  45. kctl_claw-0.2.0/src/kctl_claw/core/exceptions.py +38 -0
  46. kctl_claw-0.2.0/src/kctl_claw/core/gateway_client.py +61 -0
  47. kctl_claw-0.2.0/src/kctl_claw/core/models.py +133 -0
  48. kctl_claw-0.2.0/src/kctl_claw/core/output.py +5 -0
  49. kctl_claw-0.2.0/src/kctl_claw/core/resolve.py +63 -0
  50. kctl_claw-0.2.0/tests/__init__.py +0 -0
  51. kctl_claw-0.2.0/tests/conftest.py +196 -0
  52. kctl_claw-0.2.0/tests/test_commands/__init__.py +0 -0
  53. kctl_claw-0.2.0/tests/test_commands/test_agents.py +84 -0
  54. kctl_claw-0.2.0/tests/test_commands/test_ai.py +91 -0
  55. kctl_claw-0.2.0/tests/test_commands/test_backup.py +94 -0
  56. kctl_claw-0.2.0/tests/test_commands/test_config_cmd.py +77 -0
  57. kctl_claw-0.2.0/tests/test_commands/test_cron.py +77 -0
  58. kctl_claw-0.2.0/tests/test_commands/test_deploy.py +97 -0
  59. kctl_claw-0.2.0/tests/test_commands/test_env.py +113 -0
  60. kctl_claw-0.2.0/tests/test_commands/test_health.py +60 -0
  61. kctl_claw-0.2.0/tests/test_commands/test_logs.py +63 -0
  62. kctl_claw-0.2.0/tests/test_commands/test_mcp.py +98 -0
  63. kctl_claw-0.2.0/tests/test_commands/test_memory.py +110 -0
  64. kctl_claw-0.2.0/tests/test_commands/test_security.py +112 -0
  65. kctl_claw-0.2.0/tests/test_commands/test_skills.py +68 -0
  66. kctl_claw-0.2.0/tests/test_commands/test_status.py +60 -0
  67. kctl_claw-0.2.0/tests/test_commands/test_telegram.py +77 -0
  68. kctl_claw-0.2.0/tests/test_commands/test_trading.py +97 -0
  69. kctl_claw-0.2.0/tests/test_config.py +82 -0
  70. kctl_claw-0.2.0/tests/test_config_manager.py +63 -0
  71. kctl_claw-0.2.0/tests/test_docker_client.py +88 -0
  72. kctl_claw-0.2.0/tests/test_exceptions.py +39 -0
  73. kctl_claw-0.2.0/tests/test_gateway_client.py +72 -0
  74. kctl_claw-0.2.0/tests/test_models.py +63 -0
  75. kctl_claw-0.2.0/tests/test_output.py +74 -0
  76. kctl_claw-0.2.0/tests/test_resolve.py +136 -0
@@ -0,0 +1,33 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ *.egg
6
+ dist/
7
+ build/
8
+ .eggs/
9
+
10
+ # Virtual environments
11
+ .venv/
12
+ venv/
13
+
14
+ # IDE
15
+ .idea/
16
+ .vscode/
17
+ *.swp
18
+ *.swo
19
+
20
+ # Testing
21
+ .pytest_cache/
22
+ .coverage
23
+ htmlcov/
24
+ .mypy_cache/
25
+ .ruff_cache/
26
+
27
+ # OS
28
+ .DS_Store
29
+ Thumbs.db
30
+
31
+ # Environment
32
+ .env
33
+ .env.local
@@ -0,0 +1,19 @@
1
+ Metadata-Version: 2.4
2
+ Name: kctl-claw
3
+ Version: 0.2.0
4
+ Summary: Kodemeio OpenClaw CLI — manage AI agent gateway instances
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: croniter>=6.0.0
7
+ Requires-Dist: httpx>=0.28.0
8
+ Requires-Dist: kctl-lib>=0.4.0
9
+ Requires-Dist: pydantic>=2.10.0
10
+ Requires-Dist: pyyaml>=6.0.2
11
+ Requires-Dist: rich>=13.9.0
12
+ Requires-Dist: typer>=0.15.0
13
+ Provides-Extra: dev
14
+ Requires-Dist: mypy>=1.14.0; extra == 'dev'
15
+ Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
16
+ Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
17
+ Requires-Dist: pytest>=8.3.0; extra == 'dev'
18
+ Requires-Dist: ruff>=0.9.0; extra == 'dev'
19
+ Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
@@ -0,0 +1,205 @@
1
+ # kctl-claw
2
+
3
+ Kodemeio OpenClaw CLI — manage AI agent gateway instances from the terminal.
4
+
5
+ ## Installation
6
+
7
+ **Development (editable):**
8
+ ```bash
9
+ uv pip install -e ".[dev]"
10
+ ```
11
+
12
+ **Production (from source):**
13
+ ```bash
14
+ pip install /path/to/kctl-claw/
15
+ ```
16
+
17
+ **Container (Dockerfile):**
18
+ The CLI is installed automatically inside the Docker image — no additional steps needed.
19
+
20
+ ## Quick Start
21
+
22
+ ```bash
23
+ # Status overview
24
+ kctl-claw status overview
25
+
26
+ # Health check
27
+ kctl-claw health check
28
+
29
+ # Tail gateway logs
30
+ kctl-claw logs tail --lines 50
31
+
32
+ # List agents
33
+ kctl-claw agents list
34
+
35
+ # List cron jobs
36
+ kctl-claw cron list
37
+
38
+ # Create a backup
39
+ kctl-claw backup create
40
+ ```
41
+
42
+ ## Command Groups
43
+
44
+ ### Core Operations
45
+
46
+ | Group | Description |
47
+ |---|---|
48
+ | `agents` | Manage OpenClaw agents |
49
+ | `ai` | AI usage and cost analytics |
50
+ | `backup` | Backup and restore OpenClaw volumes |
51
+ | `config` | Manage OpenClaw configuration files |
52
+ | `cron` | Manage cron jobs |
53
+ | `deploy` | Deploy and manage the OpenClaw gateway container |
54
+ | `env` | Manage environment variables (.env.prod vs .env.example) |
55
+ | `health` | Deep health checks for gateway, configs, and Docker |
56
+ | `logs` | View OpenClaw gateway logs |
57
+ | `mcp` | Manage MCP server registry and tool profiles |
58
+ | `memory` | Manage agent memory and knowledge graph |
59
+ | `security` | Security audit and credential management |
60
+ | `skills` | Manage OpenClaw skills |
61
+ | `status` | Quick status dashboard |
62
+ | `telegram` | Manage Telegram bot configuration |
63
+ | `trading` | Trading bot operations (JournaltxDevBot) |
64
+
65
+ ### Diagnostics & Debugging (SP6)
66
+
67
+ | Group | Description |
68
+ |---|---|
69
+ | `agents-test` | Run agent integration and regression tests |
70
+ | `config-drift` | Detect and reconcile config drift between environments |
71
+ | `cron-debug` | Debug and inspect cron job execution |
72
+ | `docker` | Docker container and image management |
73
+ | `doctor` | Diagnose environment, config, and connectivity issues |
74
+ | `lint` | Lint OpenClaw configs, manifests, and skill definitions |
75
+ | `mcp-test` | Test MCP server connectivity and tool invocations |
76
+ | `monitor` | Real-time gateway metrics and uptime monitoring |
77
+ | `pipeline` | Manage and inspect agent execution pipelines |
78
+ | `prompts` | Manage and preview system prompts |
79
+ | `skills-test` | Run skill unit and integration tests |
80
+ | `test` | General test runner for OpenClaw components |
81
+
82
+ Run `kctl-claw <group> --help` for subcommands within each group.
83
+
84
+ ## Global Options
85
+
86
+ | Flag | Short | Default | Description |
87
+ |---|---|---|---|
88
+ | `--json` | | false | Output as JSON |
89
+ | `--quiet` | `-q` | false | Suppress info messages |
90
+ | `--format` | `-f` | `pretty` | Output format: `pretty` / `json` / `csv` / `yaml` |
91
+ | `--no-header` | | false | Omit table headers |
92
+ | `--profile` | `-p` | | Config profile name |
93
+ | `--root` | | | Project root override (overrides auto-detection) |
94
+ | `--live` | | false | Push config changes and trigger reload |
95
+ | `--version` | `-V` | | Show version and exit |
96
+
97
+ All options apply globally before the subcommand and can be combined:
98
+
99
+ ```bash
100
+ kctl-claw --json --profile staging agents list
101
+ kctl-claw --format yaml health check
102
+ kctl-claw --quiet --no-header cron list
103
+ ```
104
+
105
+ ## Aliases
106
+
107
+ | Alias | Expands to |
108
+ |---|---|
109
+ | `st` | `status overview` |
110
+ | `hl` | `health check` |
111
+ | `cl` | `cron list` |
112
+ | `al` | `agents list` |
113
+ | `ml` | `mcp list` |
114
+ | `lt` | `logs tail` |
115
+ | `bc` | `backup create` |
116
+ | `du` | `deploy up` |
117
+
118
+ ## Configuration
119
+
120
+ The CLI stores settings in `~/.config/kodemeio/config.yaml`. Use `kctl-claw config init` to create an initial profile, or edit the file directly:
121
+
122
+ ```yaml
123
+ default_profile: default
124
+
125
+ profiles:
126
+ default:
127
+ claw:
128
+ project_root: /path/to/kodemeio-openclaw
129
+ gateway_url: https://openclaw.kodeme.io
130
+ gateway_token: ${OPENCLAW_GATEWAY_TOKEN}
131
+ compose_file: docker-compose.prod.yml
132
+ env_file: .env.prod
133
+
134
+ staging:
135
+ claw:
136
+ project_root: /path/to/kodemeio-openclaw-staging
137
+ gateway_url: https://openclaw-staging.kodeme.io
138
+ gateway_token: ${OPENCLAW_STAGING_TOKEN}
139
+ ```
140
+
141
+ Switch profiles with `--profile` or the `KCTL_CLAW_PROFILE` environment variable. The project root is also auto-detected by walking up from the current directory looking for `config/openclaw.json`.
142
+
143
+ ### Config Subcommands
144
+
145
+ ```bash
146
+ kctl-claw config init # Create initial profile interactively
147
+ kctl-claw config show # Show current profile (secrets masked)
148
+ kctl-claw config validate # Validate config file syntax and required fields
149
+ kctl-claw config profiles # List all available profiles
150
+ kctl-claw config current # Print active profile name
151
+ kctl-claw config add # Add a new profile
152
+ kctl-claw config use # Switch default profile
153
+ kctl-claw config set # Set a single config key
154
+ kctl-claw config remove # Delete a profile
155
+ ```
156
+
157
+ ## Shell Completions
158
+
159
+ Install shell completions for faster command entry:
160
+
161
+ ```bash
162
+ # Zsh
163
+ kctl-claw --install-completion zsh
164
+ # Then add to ~/.zshrc:
165
+ source ~/.zsh_completions/_kctl-claw
166
+
167
+ # Bash
168
+ kctl-claw --install-completion bash
169
+ # Then add to ~/.bashrc:
170
+ source ~/.bash_completions/kctl-claw
171
+
172
+ # Fish
173
+ kctl-claw --install-completion fish
174
+ ```
175
+
176
+ After installing, restart your shell or source your rc file. Tab-completion covers command groups, subcommands, and common flag values.
177
+
178
+ ## Environment Variables
179
+
180
+ | Variable | Description |
181
+ |---|---|
182
+ | `KCTL_CLAW_PROFILE` | Override active profile (equivalent to `--profile`) |
183
+ | `OPENCLAW_GATEWAY_TOKEN` | Gateway API token (referenced in config via `${...}`) |
184
+ | `OPENCLAW_STAGING_TOKEN` | Staging gateway token |
185
+
186
+ ## Development
187
+
188
+ ```bash
189
+ # Run tests
190
+ uv run pytest tests/ -v
191
+
192
+ # Lint
193
+ uv run ruff check src/ tests/
194
+
195
+ # Format
196
+ uv run ruff format src/ tests/
197
+
198
+ # Type check
199
+ uv run mypy src/kctl_claw/
200
+
201
+ # All checks
202
+ uv run ruff check src/ tests/ && uv run ruff format src/ tests/ && uv run mypy src/kctl_claw/ && uv run pytest tests/
203
+ ```
204
+
205
+ For full command reference and admin skill integration, see the `openclaw-admin` Claude Code skill in `skills/openclaw-admin/`.
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "kctl-claw"
7
+ version = "0.2.0"
8
+ description = "Kodemeio OpenClaw CLI — manage AI agent gateway instances"
9
+ requires-python = ">=3.12"
10
+ dependencies = [
11
+ "kctl-lib>=0.4.0",
12
+ "typer>=0.15.0",
13
+ "rich>=13.9.0",
14
+ "pydantic>=2.10.0",
15
+ "pyyaml>=6.0.2",
16
+ "httpx>=0.28.0",
17
+ "croniter>=6.0.0",
18
+ ]
19
+
20
+ [project.optional-dependencies]
21
+ dev = [
22
+ "pytest>=8.3.0",
23
+ "pytest-httpx>=0.35.0",
24
+ "pytest-cov>=6.0.0",
25
+ "ruff>=0.9.0",
26
+ "mypy>=1.14.0",
27
+ "types-PyYAML>=6.0.0",
28
+ ]
29
+
30
+ [project.scripts]
31
+ kctl-claw = "kctl_claw.cli:_run"
32
+
33
+ [tool.uv.sources]
34
+ kctl-lib = { workspace = true }
35
+
36
+ [project.entry-points."kctl_claw.plugins"]
37
+
38
+ [tool.hatch.build.targets.wheel]
39
+ packages = ["src/kctl_claw"]
40
+
41
+ [tool.ruff]
42
+ target-version = "py312"
43
+ line-length = 120
44
+
45
+ [tool.mypy]
46
+ python_version = "3.12"
47
+ strict = true
@@ -0,0 +1,309 @@
1
+ ---
2
+ name: openclaw-admin
3
+ description: >
4
+ OpenClaw AI gateway administration for kodemeio infrastructure.
5
+ Covers agent management, cron jobs, MCP servers, skills, memory, trading,
6
+ AI cost analytics, deployment, backup/restore, security audit, and Telegram
7
+ bot management. Use when working with kctl-claw CLI or managing OpenClaw.
8
+ version: 1.0.0
9
+ allowed-tools:
10
+ - Bash
11
+ - Read
12
+ - Write
13
+ - Edit
14
+ - Glob
15
+ - Grep
16
+ ---
17
+
18
+ # OpenClaw Administration for Kodemeio
19
+
20
+ ## Quick Commands
21
+
22
+ Most frequent operations at a glance:
23
+
24
+ | Command | Description |
25
+ |---------|-------------|
26
+ | `kctl-claw st` | Status overview (alias) |
27
+ | `kctl-claw hl` | Health check (alias) |
28
+ | `kctl-claw al` | List agents (alias) |
29
+ | `kctl-claw cl` | List cron jobs (alias) |
30
+ | `kctl-claw ml` | List MCP servers (alias) |
31
+ | `kctl-claw lt` | Tail logs (alias) |
32
+ | `kctl-claw bc` | Create backup (alias) |
33
+ | `kctl-claw du` | Deploy up (alias) |
34
+ | `kctl-claw status overview` | Full status dashboard |
35
+ | `kctl-claw health check` | Deep health check |
36
+ | `kctl-claw config validate` | Validate config files |
37
+ | `kctl-claw agents list` | List all agents with status |
38
+ | `kctl-claw cron list` | List all 27 cron jobs |
39
+ | `kctl-claw mcp list` | List 23 MCP servers |
40
+ | `kctl-claw security audit` | Run 15-point security audit |
41
+ | `kctl-claw backup create` | Create volume backup |
42
+ | `kctl-claw deploy up` | Start gateway |
43
+ | `kctl-claw ai usage` | AI cost & usage stats |
44
+ | `kctl-claw trading status` | Trading bot status |
45
+ | `kctl-claw memory stats` | Memory graph statistics |
46
+
47
+ ## Architecture
48
+
49
+ OpenClaw is an AI Agent Gateway running in Docker on Dokploy.
50
+
51
+ - **Gateway**: Port 18789, Traefik reverse proxy → openclaw.kodeme.io
52
+ - **Version**: 2026.3.24 (pinned in docker-compose.prod.yml)
53
+ - **Agents**: 5 autonomous bots (4 company operators + 1 team assistant)
54
+ - KodemeioDevBot — Opus 4.6, CEO/CTO/Sales/Finance/DevOps for kodeme.io
55
+ - KontenosDevBot — Sonnet 4, Content/Social/Products for kontenos.com
56
+ - JournaltxDevBot — Sonnet 4, Trading/Risk/Portfolio for journaltx.com
57
+ - KidneuroDevBot — Sonnet 4, Healthcare/Product for kidneuro.io
58
+ - KodemeioTeam — Sonnet 4, Team read-only assistant (no write ops)
59
+ - **MCP Servers**: 23 total (17 custom + 10 external npm)
60
+ - **Cron Jobs**: 27 autonomous jobs (Opus for strategy, Sonnet for content, Flash for routine)
61
+ - **Tool Profiles**: 6 profiles limiting per-turn MCP exposure
62
+ - **Volumes**: `openclaw-data` (config+auth), `openclaw-workspace` (agent memory+workspace)
63
+ - **Config**: `config/openclaw.json` (main), `config/config.json` (MCP registry), `config/cron/jobs.json`
64
+ - **Entry point**: `docker-compose.prod.yml` on dokploy.kodeme.io
65
+
66
+ ## Status & Health
67
+
68
+ | Command | Description |
69
+ |---------|-------------|
70
+ | `kctl-claw status overview` | Full dashboard: gateway, agents, cron, MCP, memory |
71
+ | `kctl-claw status agents` | Agent status summary |
72
+ | `kctl-claw status cron` | Cron job status summary |
73
+ | `kctl-claw status mcp` | MCP server connectivity summary |
74
+ | `kctl-claw health check` | Deep check: gateway API, Docker, configs, MCP reachability |
75
+ | `kctl-claw health watch` | Continuous health monitoring (Ctrl+C to stop) |
76
+ | `kctl-claw health --json` | Machine-readable health output |
77
+
78
+ ## Agent Management
79
+
80
+ | Command | Description |
81
+ |---------|-------------|
82
+ | `kctl-claw agents list` | List all agents with name, model, profile, status |
83
+ | `kctl-claw agents get <name>` | Full agent config details |
84
+ | `kctl-claw agents set-model <name> <model>` | Change agent model (e.g. claude-opus-4-6) |
85
+ | `kctl-claw agents set-profile <name> <profile>` | Change tool profile |
86
+ | `kctl-claw agents enable <name>` | Enable a disabled agent |
87
+ | `kctl-claw agents disable <name>` | Disable an agent |
88
+ | `kctl-claw agents sessions <name>` | List active sessions for agent |
89
+ | `kctl-claw agents reload` | Trigger agent config hot-reload |
90
+
91
+ Agent names: `kodemeiodev`, `kontenosdev`, `journaltxdev`, `kidneurodev`, `kodeimeoteam`
92
+
93
+ ## Cron Management
94
+
95
+ | Command | Description |
96
+ |---------|-------------|
97
+ | `kctl-claw cron list` | List all 27 cron jobs with schedule, agent, status |
98
+ | `kctl-claw cron get <job-id>` | Job details: schedule, agent, model, last run |
99
+ | `kctl-claw cron enable <job-id>` | Enable a disabled job |
100
+ | `kctl-claw cron disable <job-id>` | Disable a job |
101
+ | `kctl-claw cron trigger <job-id>` | Trigger immediate execution |
102
+ | `kctl-claw cron history <job-id>` | Recent execution history |
103
+ | `kctl-claw cron set-schedule <job-id> <cron-expr>` | Change cron schedule |
104
+
105
+ Important: Never disable `system-health-check` or `daily-self-reflection` without explicit user request.
106
+
107
+ ## MCP Servers
108
+
109
+ | Command | Description |
110
+ |---------|-------------|
111
+ | `kctl-claw mcp list` | List all 23 MCP servers with type and status |
112
+ | `kctl-claw mcp get <server-id>` | Server details: command, env vars, tools |
113
+ | `kctl-claw mcp test <server-id>` | Test connectivity / spawn server |
114
+ | `kctl-claw mcp profiles` | List tool profiles and their server assignments |
115
+ | `kctl-claw mcp profile-get <profile>` | Profile details: servers, denied tools |
116
+ | `kctl-claw mcp assign <server-id> <profile>` | Add server to profile |
117
+ | `kctl-claw mcp remove <server-id> <profile>` | Remove server from profile |
118
+
119
+ Profiles: `default`, `content`, `trading`, `kidneuro`, `team`, `all`
120
+
121
+ ## Skill Management
122
+
123
+ | Command | Description |
124
+ |---------|-------------|
125
+ | `kctl-claw skills list` | List all 15 skills with agent assignments |
126
+ | `kctl-claw skills get <name>` | Skill details: command, description, agents |
127
+ | `kctl-claw skills create <name>` | Scaffold new skill from template |
128
+ | `kctl-claw skills delete <name>` | Remove skill |
129
+ | `kctl-claw skills assign <name> <agent>` | Assign skill to agent |
130
+ | `kctl-claw skills unassign <name> <agent>` | Remove skill from agent |
131
+ | `kctl-claw skills reload` | Hot-reload skills (requires `--live`) |
132
+
133
+ ## Memory & Knowledge
134
+
135
+ | Command | Description |
136
+ |---------|-------------|
137
+ | `kctl-claw memory stats` | Memory graph stats: nodes, edges, topics |
138
+ | `kctl-claw memory search <query>` | BM25+vector hybrid search |
139
+ | `kctl-claw memory export` | Export memory graph to JSON |
140
+ | `kctl-claw memory prune --older-than <days>` | Prune entries older than N days |
141
+ | `kctl-claw memory clear <agent>` | Clear all memory for an agent (destructive) |
142
+
143
+ Memory prune requires an explicit age threshold — no default bulk delete.
144
+ Always backup before `memory clear`.
145
+
146
+ ## Deployment
147
+
148
+ | Command | Description |
149
+ |---------|-------------|
150
+ | `kctl-claw deploy up` | Start gateway (`docker compose up -d`) |
151
+ | `kctl-claw deploy down` | Stop gateway |
152
+ | `kctl-claw deploy restart` | Restart gateway container |
153
+ | `kctl-claw deploy pull` | Pull latest image |
154
+ | `kctl-claw deploy verify` | Verify image hash and version |
155
+ | `kctl-claw deploy status` | Container status and uptime |
156
+ | `kctl-claw deploy logs` | Recent deploy logs |
157
+
158
+ Run `kctl-claw security audit` and `kctl-claw backup create` before deploying to production.
159
+ Use `--live` only when immediate config effect is required.
160
+
161
+ ## Backup & Restore
162
+
163
+ | Command | Description |
164
+ |---------|-------------|
165
+ | `kctl-claw backup create` | Create timestamped backup of both volumes |
166
+ | `kctl-claw backup list` | List available backups with size and date |
167
+ | `kctl-claw backup restore <backup-id>` | Restore volumes from backup |
168
+ | `kctl-claw backup prune --keep <n>` | Delete old backups, keep latest N |
169
+ | `kctl-claw backup verify <backup-id>` | Verify backup integrity |
170
+
171
+ Always run `kctl-claw backup create` before: memory clear, restore, deploy, config reload with destructive changes.
172
+
173
+ ## Trading Operations
174
+
175
+ | Command | Description |
176
+ |---------|-------------|
177
+ | `kctl-claw trading status` | Trading bot status: active, paused, positions |
178
+ | `kctl-claw trading portfolio` | Portfolio summary: assets, P&L, allocation |
179
+ | `kctl-claw trading kill-switch` | Emergency stop all trading (requires confirmation) |
180
+ | `kctl-claw trading risk-limits` | Show current risk limits |
181
+ | `kctl-claw trading set-risk <key> <value>` | Update a risk limit parameter |
182
+ | `kctl-claw trading history` | Recent trade history |
183
+
184
+ For trading kill switch: always confirm with user before executing.
185
+
186
+ ## AI Cost Analytics
187
+
188
+ | Command | Description |
189
+ |---------|-------------|
190
+ | `kctl-claw ai usage` | Usage summary: tokens, requests, cost today/month |
191
+ | `kctl-claw ai projection` | Monthly cost projection based on current rate |
192
+ | `kctl-claw ai breakdown` | Cost breakdown by model (Opus/Sonnet/Flash) |
193
+ | `kctl-claw ai budget` | Budget status and alerts |
194
+ | `kctl-claw ai by-agent` | Usage breakdown per agent |
195
+ | `kctl-claw ai by-cron` | Usage breakdown per cron job |
196
+
197
+ ## Security
198
+
199
+ | Command | Description |
200
+ |---------|-------------|
201
+ | `kctl-claw security audit` | Run 15-point security checklist |
202
+ | `kctl-claw security credentials` | List credentials (redacted values) |
203
+ | `kctl-claw security allowlist` | Show Telegram user allowlist |
204
+ | `kctl-claw security allowlist-add <user-id>` | Add user to Telegram allowlist |
205
+ | `kctl-claw security allowlist-remove <user-id>` | Remove user from allowlist |
206
+ | `kctl-claw security sandbox-status` | Show agent sandbox configuration |
207
+
208
+ Always show redacted values for env vars and credentials — never expose secrets.
209
+ Security audit must pass before any production deployment.
210
+
211
+ ## Telegram Bots
212
+
213
+ | Command | Description |
214
+ |---------|-------------|
215
+ | `kctl-claw telegram list` | List all 5 bots with username and status |
216
+ | `kctl-claw telegram get <bot>` | Bot details: token (redacted), agent binding |
217
+ | `kctl-claw telegram bindings` | Show agent ↔ bot bindings |
218
+ | `kctl-claw telegram test <bot>` | Test bot connectivity via Telegram API |
219
+ | `kctl-claw telegram allowlist` | Show allowed user IDs |
220
+ | `kctl-claw telegram send <bot> <user-id> <message>` | Send test message |
221
+
222
+ Bots: `KodemeioDevBot`, `KontenosDevBot`, `JournaltxDevBot`, `KidneuroDevBot`, `KodemeioTeamBot`
223
+
224
+ ## Environment Vars
225
+
226
+ | Command | Description |
227
+ |---------|-------------|
228
+ | `kctl-claw env check` | Validate .env.prod against .env.example template |
229
+ | `kctl-claw env diff` | Show keys present in example but missing from prod |
230
+ | `kctl-claw env list` | List all env var keys (values redacted) |
231
+ | `kctl-claw env template` | Regenerate .env.example from current .env.prod (redacted) |
232
+
233
+ Never output actual secret values. Always display redacted placeholders.
234
+
235
+ ## Logs
236
+
237
+ | Command | Description |
238
+ |---------|-------------|
239
+ | `kctl-claw logs tail` | Tail gateway logs (like `docker compose logs -f`) |
240
+ | `kctl-claw logs tail --lines <n>` | Last N lines then follow |
241
+ | `kctl-claw logs search <pattern>` | Search logs for pattern |
242
+ | `kctl-claw logs agent <name>` | Filter logs for a specific agent |
243
+ | `kctl-claw logs errors` | Show only ERROR/FATAL log lines |
244
+ | `kctl-claw logs since <datetime>` | Logs since a specific time |
245
+
246
+ ## Aliases
247
+
248
+ Short commands for fast terminal use (hidden from `--help`):
249
+
250
+ | Alias | Expands To |
251
+ |-------|-----------|
252
+ | `kctl-claw st` | `kctl-claw status overview` |
253
+ | `kctl-claw hl` | `kctl-claw health check` |
254
+ | `kctl-claw cl` | `kctl-claw cron list` |
255
+ | `kctl-claw al` | `kctl-claw agents list` |
256
+ | `kctl-claw ml` | `kctl-claw mcp list` |
257
+ | `kctl-claw lt` | `kctl-claw logs tail` |
258
+ | `kctl-claw bc` | `kctl-claw backup create` |
259
+ | `kctl-claw du` | `kctl-claw deploy up` |
260
+
261
+ All global options (`--json`, `--format`, `--profile`, `--quiet`, `--live`) are forwarded by aliases.
262
+
263
+ ## Output Formats
264
+
265
+ | Flag | Description | Use Case |
266
+ |------|-------------|----------|
267
+ | `--json` | JSON output | Scripting, CI/CD pipelines |
268
+ | `--format csv` | CSV table output | Spreadsheet import |
269
+ | `--format yaml` | YAML output | Config review |
270
+ | `--format pretty` | Rich tables (default) | Human reading |
271
+ | `--quiet` / `-q` | Suppress info messages | Scripting |
272
+ | `--no-header` | Omit table header row | Scripting |
273
+
274
+ Example for scripting:
275
+ ```bash
276
+ kctl-claw --json agents list | jq '.[].name'
277
+ kctl-claw --format csv cron list > cron-jobs.csv
278
+ kctl-claw --quiet backup create && echo "Backup OK"
279
+ ```
280
+
281
+ ## Troubleshooting
282
+
283
+ | Symptom | Likely Cause | Resolution |
284
+ |---------|-------------|------------|
285
+ | `Gateway connection refused` | Container not running | `kctl-claw deploy up` |
286
+ | `Config validation failed` | Malformed JSON in config | `kctl-claw config validate` + fix errors |
287
+ | `MCP server unreachable` | Wrong path or env vars | `kctl-claw mcp test <server-id>` |
288
+ | `Cron not firing` | Job disabled or wrong schedule | `kctl-claw cron get <job-id>` |
289
+ | `Agent not responding` | Token exhausted or model error | `kctl-claw logs agent <name>` |
290
+ | `Backup restore fails` | Volume busy or wrong backup-id | `kctl-claw deploy down` then restore |
291
+ | `Trading bot stuck` | Risk limit hit | `kctl-claw trading status` + check limits |
292
+ | `High AI costs` | Opus used for routine tasks | `kctl-claw ai breakdown` + tune cron models |
293
+ | `Telegram bot offline` | Webhook conflict or invalid token | `kctl-claw telegram test <bot>` |
294
+ | `Memory search empty` | No entries or wrong agent scope | `kctl-claw memory stats` |
295
+
296
+ For persistent issues, check `kctl-claw logs errors` and `kctl-claw health check --json`.
297
+
298
+ ## Rules
299
+
300
+ Enforcement rules for safe OpenClaw operations:
301
+
302
+ 1. **Validate before reload**: Always run `kctl-claw config validate` before `kctl-claw config reload`
303
+ 2. **Backup before destructive ops**: Always run `kctl-claw backup create` before memory clear, restore, or deploy with destructive config changes
304
+ 3. **Protect system cron jobs**: Never disable `system-health-check` or `daily-self-reflection` without explicit user request
305
+ 4. **Live flag intent**: Use `--live` only when the user wants immediate effect — default to config-only changes
306
+ 5. **Trading kill switch**: Always confirm with the user before executing `kctl-claw trading kill-switch`
307
+ 6. **Security first**: Security audit must pass (`kctl-claw security audit`) before any production deployment
308
+ 7. **Memory prune threshold**: Memory prune requires an explicit `--older-than <days>` argument — no default bulk delete
309
+ 8. **No secret exposure**: Always show redacted values for env vars and credentials — never output actual secrets
@@ -0,0 +1,3 @@
1
+ """kctl-claw: Kodemeio OpenClaw CLI."""
2
+
3
+ __version__ = "0.2.0"
@@ -0,0 +1,5 @@
1
+ """Allow running as: python -m kctl_claw."""
2
+
3
+ from kctl_claw.cli import _run
4
+
5
+ _run()