kiwi-code 0.0.39__tar.gz → 0.0.40__tar.gz

{kiwi_code-0.0.39 → kiwi_code-0.0.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiwi-code
-Version: 0.0.39
+Version: 0.0.40
 Summary: A textual-based terminal user interface application
 Project-URL: Homepage, https://meetkiwi.ai
 Project-URL: Repository, https://github.com/jetoslabs/kiwi-code
@@ -30,12 +30,16 @@ Description-Content-Type: text/markdown
 
 # Kiwi Code
 
-Kiwi Code is a terminal-first UI (TUI) for chatting with **Kiwi Actions** and managing **runs** (action results). It also integrates with the **Kiwi Runtime** (a local CLI/terminal agent) so actions can execute terminal commands on your machine.
+Kiwi Code is a terminal-first interface for chatting with **Kiwi Actions**, managing **runs** (action results), and connecting the **Kiwi Runtime** (a local CLI / terminal agent) so actions can execute terminal commands on your machine.
+
+Primary entrypoints:
 
 - **TUI:** `kiwi` (or `python -m kiwi_tui.main`)
-- **CLI:** `kiwicli` (optional; scripting / inspection)
+- **Terminal mode:** `kiwi --terminal ...`
+- **Inspection CLI:** `kiwicli` (optional; list/get style scripting)
+- **Runtime:** `kiwi-runtime`
 
-> Requires **Python 3.13+**.
+> Requires **Python 3.11+**.
 
 ---
 
@@ -43,66 +47,133 @@ Kiwi Code is a terminal-first UI (TUI) for chatting with **Kiwi Actions** and ma
 
 ### 1) Install
 
+```bash
 pip install kiwi-code
+```
+
+### 2) Log in from the terminal
+
+```bash
+kiwi login
+```
+
+This prompts for your email and password and stores tokens at:
+
+- `~/.kiwi/tokens.json`
+
+You can inspect auth state anytime with:
+
+```bash
+kiwi whoami
+```
+
+To clear saved credentials:
+
+```bash
+kiwi logout
+```
+
+### 3) Launch the TUI (unchanged default)
 
-### 2) Start the TUI
+```bash
+kiwi
+```
 
-Connect using a server preset:
+Or choose a server preset:
 
-kiwi --server app
+```bash
+kiwi --server dev
+```
 
 Available presets:
-- app (prod)
-- dev (dev)
 
-### 3) Login
+- `app` (prod)
+- `dev` (dev)
+- `local` (localhost)
 
-The TUI will prompt for login if you’re not authenticated.
+### 4) Use terminal mode instead of the full-screen TUI
 
-Tokens are stored under:
+Fresh conversation on the default action:
 
-- ~/.kiwi/tokens.json
+```bash
+kiwi --terminal "Hi, what are you doing?"
+```
 
-### 4) (Optional) Start the Runtime
+Fresh conversation for a specific action:
 
-If you want to run the runtime manually:
+```bash
+kiwi --terminal --action-id <ACTION_ID> "Inspect this repository"
+```
 
-kiwi-runtime connect --server dev --scope full
+Continue an existing run:
 
-Or for production:
+```bash
+kiwi --terminal --run-id <RUN_ID> "What changed?"
+```
 
-kiwi-runtime connect --server app --scope full
+Pipe the message on stdin:
 
-### Notes
+```bash
+echo "Summarize the latest output" | kiwi --terminal --run-id <RUN_ID>
+```
 
-- --scope full gives unrestricted access. Use restricted if you want tighter control.
-- In most cases, you can skip manual runtime startup and just use /connect-cli inside the TUI.
+Connect the local CLI runtime from terminal mode:
 
-### 2) Start the TUI
+```bash
+kiwi --terminal --connect-cli
+kiwi --terminal --connect-cli --action-id <ACTION_ID>
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
 
-Choose a server preset:
+Rules:
 
-- `app` (prod)
-- `dev` (dev)
-- `local` (localhost)
+- `kiwi` by itself still launches the TUI.
+- `--action-id` starts a **fresh** conversation for that action.
+- `--run-id` continues an **existing** run.
+- `--action-id` and `--run-id` are mutually exclusive.
+- `--connect-cli` cannot be combined with a user message.
+
+### 5) (Optional) Start the runtime manually
+
+In most cases, let Kiwi manage the runtime automatically via `/connect-cli` in the TUI or `kiwi --terminal --connect-cli` in terminal mode.
+
+If you want to run it yourself:
 
 ```bash
-uv run python -m kiwi_tui.main --server dev
+kiwi-runtime connect --server dev --scope restricted --allow "$PWD"
 ```
 
-Or, if installed as a package:
+---
+
+## Terminal mode usage
+
+### Human-readable output
 
 ```bash
-kiwi --server dev
+kiwi --terminal "Hello"
 ```
 
-### 3) Login
+This prints the run result directly in your terminal.
 
-The TUI will show a login screen if you’re not authenticated.
+### JSON output for scripts
 
-Tokens are stored under:
+```bash
+kiwi --terminal --json --action-id <ACTION_ID> "Hello"
+```
 
-- `~/.kiwi/tokens.json`
+### Disable live status streaming
+
+```bash
+kiwi --terminal --no-stream --run-id <RUN_ID> "Continue this task"
+```
+
+### Authentication in terminal mode
+
+If you are not logged in, terminal mode exits with a helpful message telling you to run:
+
+```bash
+kiwi login
+```
 
 ---
 
@@ -132,15 +203,24 @@ Some actions can execute terminal commands via a local runtime process.
 
 ### Connect the runtime to the current run
 
-Inside the TUI:
+From the TUI:
 
 - `/connect-cli`
 
+From terminal mode:
+
+```bash
+kiwi --terminal --connect-cli
+kiwi --terminal --connect-cli --action-id <ACTION_ID>
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
+
 What it does:
 
 - Ensures a local runtime exists **for the current run_id**.
-- If the runtime was disconnected (e.g., server redeploy), Kiwi Code detects it and starts a fresh one.
-- Sends the instruction prompt: “Connect to the CLI right now before asking or doing anything.”
+- If the runtime was disconnected (e.g. after a server redeploy), Kiwi Code detects it and starts a fresh one.
+- Sends the instruction prompt: `Connect to the CLI right now before asking or doing anything.`
+- In terminal mode, `--connect-cli` is a setup action only, so it **must not** be combined with a message.
 
 ### View runtime logs
 
@@ -195,9 +275,25 @@ These are designed to work even when input is blocked during streaming.
 
 ---
 
-## CLI (optional)
+## CLI overview
+
+### `kiwi`
 
-`kiwicli` provides the same “list/get” style commands for scripting and inspection.
+`kiwi` is the primary user-facing CLI.
+
+Examples:
+
+```bash
+kiwi
+kiwi login
+kiwi whoami
+kiwi --terminal "Hello"
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
+
+### `kiwicli`
+
+`kiwicli` remains available for list/get style scripting and inspection.
 
 Examples:
 
@@ -213,7 +309,7 @@ kiwicli runs get <run_id>
 
 ## Server / flags
 
-`kiwi` / `python -m kiwi_tui.main` supports runtime flags (mirrors `kiwi-runtime connect`). These flags are used when Kiwi Code needs to start a runtime.
+`kiwi` / `python -m kiwi_tui.main` supports runtime flags (mirrors `kiwi-runtime connect`). These flags are used whenever Kiwi Code needs to start a runtime, whether you are in the TUI or terminal mode.
 
 ```bash
 kiwi --server dev \
@@ -221,9 +317,23 @@ kiwi --server dev \
   --allow /some/extra/dir
 ```
 
+Terminal mode examples:
+
+```bash
+kiwi --terminal --server dev "Hello"
+kiwi --terminal --json --action-id <ACTION_ID> "Hello"
+kiwi --terminal --no-stream --run-id <RUN_ID> "Continue"
+```
+
 - `--server`: `app | dev | local | <full url>`
 - `--scope`: `restricted | full`
 - `--allow PATH`: repeatable; additional allowed directories in restricted mode
+- `--terminal`: run Kiwi in plain terminal mode instead of the full-screen TUI
+- `--action-id`: start a fresh conversation for the given action
+- `--run-id`: continue an existing run
+- `--connect-cli`: ensure runtime exists and send the connect prompt
+- `--json`: print machine-readable output for terminal mode
+- `--no-stream`: wait for the final result without live status streaming
 
 > Note: Kiwi Code does **not** modify the runtime implementation under `src/kiwi_runtime/`.
 

{kiwi_code-0.0.39 → kiwi_code-0.0.40}/README.md

@@ -1,11 +1,15 @@
 # Kiwi Code
 
-Kiwi Code is a terminal-first UI (TUI) for chatting with **Kiwi Actions** and managing **runs** (action results). It also integrates with the **Kiwi Runtime** (a local CLI/terminal agent) so actions can execute terminal commands on your machine.
+Kiwi Code is a terminal-first interface for chatting with **Kiwi Actions**, managing **runs** (action results), and connecting the **Kiwi Runtime** (a local CLI / terminal agent) so actions can execute terminal commands on your machine.
+
+Primary entrypoints:
 
 - **TUI:** `kiwi` (or `python -m kiwi_tui.main`)
-- **CLI:** `kiwicli` (optional; scripting / inspection)
+- **Terminal mode:** `kiwi --terminal ...`
+- **Inspection CLI:** `kiwicli` (optional; list/get style scripting)
+- **Runtime:** `kiwi-runtime`
 
-> Requires **Python 3.13+**.
+> Requires **Python 3.11+**.
 
 ---
 
@@ -13,66 +17,133 @@ Kiwi Code is a terminal-first UI (TUI) for chatting with **Kiwi Actions** and ma
 
 ### 1) Install
 
+```bash
 pip install kiwi-code
+```
+
+### 2) Log in from the terminal
+
+```bash
+kiwi login
+```
+
+This prompts for your email and password and stores tokens at:
+
+- `~/.kiwi/tokens.json`
+
+You can inspect auth state anytime with:
+
+```bash
+kiwi whoami
+```
+
+To clear saved credentials:
+
+```bash
+kiwi logout
+```
+
+### 3) Launch the TUI (unchanged default)
 
-### 2) Start the TUI
+```bash
+kiwi
+```
 
-Connect using a server preset:
+Or choose a server preset:
 
-kiwi --server app
+```bash
+kiwi --server dev
+```
 
 Available presets:
-- app (prod)
-- dev (dev)
 
-### 3) Login
+- `app` (prod)
+- `dev` (dev)
+- `local` (localhost)
 
-The TUI will prompt for login if you’re not authenticated.
+### 4) Use terminal mode instead of the full-screen TUI
 
-Tokens are stored under:
+Fresh conversation on the default action:
 
-- ~/.kiwi/tokens.json
+```bash
+kiwi --terminal "Hi, what are you doing?"
+```
 
-### 4) (Optional) Start the Runtime
+Fresh conversation for a specific action:
 
-If you want to run the runtime manually:
+```bash
+kiwi --terminal --action-id <ACTION_ID> "Inspect this repository"
+```
 
-kiwi-runtime connect --server dev --scope full
+Continue an existing run:
 
-Or for production:
+```bash
+kiwi --terminal --run-id <RUN_ID> "What changed?"
+```
 
-kiwi-runtime connect --server app --scope full
+Pipe the message on stdin:
 
-### Notes
+```bash
+echo "Summarize the latest output" | kiwi --terminal --run-id <RUN_ID>
+```
 
-- --scope full gives unrestricted access. Use restricted if you want tighter control.
-- In most cases, you can skip manual runtime startup and just use /connect-cli inside the TUI.
+Connect the local CLI runtime from terminal mode:
 
-### 2) Start the TUI
+```bash
+kiwi --terminal --connect-cli
+kiwi --terminal --connect-cli --action-id <ACTION_ID>
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
 
-Choose a server preset:
+Rules:
 
-- `app` (prod)
-- `dev` (dev)
-- `local` (localhost)
+- `kiwi` by itself still launches the TUI.
+- `--action-id` starts a **fresh** conversation for that action.
+- `--run-id` continues an **existing** run.
+- `--action-id` and `--run-id` are mutually exclusive.
+- `--connect-cli` cannot be combined with a user message.
+
+### 5) (Optional) Start the runtime manually
+
+In most cases, let Kiwi manage the runtime automatically via `/connect-cli` in the TUI or `kiwi --terminal --connect-cli` in terminal mode.
+
+If you want to run it yourself:
 
 ```bash
-uv run python -m kiwi_tui.main --server dev
+kiwi-runtime connect --server dev --scope restricted --allow "$PWD"
 ```
 
-Or, if installed as a package:
+---
+
+## Terminal mode usage
+
+### Human-readable output
 
 ```bash
-kiwi --server dev
+kiwi --terminal "Hello"
 ```
 
-### 3) Login
+This prints the run result directly in your terminal.
 
-The TUI will show a login screen if you’re not authenticated.
+### JSON output for scripts
 
-Tokens are stored under:
+```bash
+kiwi --terminal --json --action-id <ACTION_ID> "Hello"
+```
 
-- `~/.kiwi/tokens.json`
+### Disable live status streaming
+
+```bash
+kiwi --terminal --no-stream --run-id <RUN_ID> "Continue this task"
+```
+
+### Authentication in terminal mode
+
+If you are not logged in, terminal mode exits with a helpful message telling you to run:
+
+```bash
+kiwi login
+```
 
 ---
 
@@ -102,15 +173,24 @@ Some actions can execute terminal commands via a local runtime process.
 
 ### Connect the runtime to the current run
 
-Inside the TUI:
+From the TUI:
 
 - `/connect-cli`
 
+From terminal mode:
+
+```bash
+kiwi --terminal --connect-cli
+kiwi --terminal --connect-cli --action-id <ACTION_ID>
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
+
 What it does:
 
 - Ensures a local runtime exists **for the current run_id**.
-- If the runtime was disconnected (e.g., server redeploy), Kiwi Code detects it and starts a fresh one.
-- Sends the instruction prompt: “Connect to the CLI right now before asking or doing anything.”
+- If the runtime was disconnected (e.g. after a server redeploy), Kiwi Code detects it and starts a fresh one.
+- Sends the instruction prompt: `Connect to the CLI right now before asking or doing anything.`
+- In terminal mode, `--connect-cli` is a setup action only, so it **must not** be combined with a message.
 
 ### View runtime logs
 
@@ -165,9 +245,25 @@ These are designed to work even when input is blocked during streaming.
 
 ---
 
-## CLI (optional)
+## CLI overview
+
+### `kiwi`
 
-`kiwicli` provides the same “list/get” style commands for scripting and inspection.
+`kiwi` is the primary user-facing CLI.
+
+Examples:
+
+```bash
+kiwi
+kiwi login
+kiwi whoami
+kiwi --terminal "Hello"
+kiwi --terminal --connect-cli --run-id <RUN_ID>
+```
+
+### `kiwicli`
+
+`kiwicli` remains available for list/get style scripting and inspection.
 
 Examples:
 
@@ -183,7 +279,7 @@ kiwicli runs get <run_id>
 
 ## Server / flags
 
-`kiwi` / `python -m kiwi_tui.main` supports runtime flags (mirrors `kiwi-runtime connect`). These flags are used when Kiwi Code needs to start a runtime.
+`kiwi` / `python -m kiwi_tui.main` supports runtime flags (mirrors `kiwi-runtime connect`). These flags are used whenever Kiwi Code needs to start a runtime, whether you are in the TUI or terminal mode.
 
 ```bash
 kiwi --server dev \
@@ -191,9 +287,23 @@ kiwi --server dev \
   --allow /some/extra/dir
 ```
 
+Terminal mode examples:
+
+```bash
+kiwi --terminal --server dev "Hello"
+kiwi --terminal --json --action-id <ACTION_ID> "Hello"
+kiwi --terminal --no-stream --run-id <RUN_ID> "Continue"
+```
+
 - `--server`: `app | dev | local | <full url>`
 - `--scope`: `restricted | full`
 - `--allow PATH`: repeatable; additional allowed directories in restricted mode
+- `--terminal`: run Kiwi in plain terminal mode instead of the full-screen TUI
+- `--action-id`: start a fresh conversation for the given action
+- `--run-id`: continue an existing run
+- `--connect-cli`: ensure runtime exists and send the connect prompt
+- `--json`: print machine-readable output for terminal mode
+- `--no-stream`: wait for the final result without live status streaming
 
 > Note: Kiwi Code does **not** modify the runtime implementation under `src/kiwi_runtime/`.
 

{kiwi_code-0.0.39 → kiwi_code-0.0.40}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiwi-code"
-version = "0.0.39"
+version = "0.0.40"
 description = "A textual-based terminal user interface application"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.11,<4.0"