rathflow-cli 0.1.0__tar.gz

rathflow_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rath Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rathflow_cli-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: rathflow-cli
+Version: 0.1.0
+Summary: RathFlow command line client: sessions, memory, sandboxes, assets and billing over the RathFlow REST API.
+Author: Rath Team
+License-Expression: MIT
+Project-URL: Homepage, https://rathflow.lynwe.com/
+Project-URL: Repository, https://github.com/Rath-Team/rathflow-cli
+Project-URL: Issues, https://github.com/Rath-Team/rathflow-cli/issues
+Project-URL: Changelog, https://github.com/Rath-Team/rathflow-cli/blob/main/CHANGELOG.md
+Keywords: rathflow,cli,agent,sessions,memory,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Provides-Extra: socks
+Requires-Dist: httpx[socks]; extra == "socks"
+Dynamic: license-file
+
+# rathflow-cli
+
+[![PyPI](https://img.shields.io/pypi/v/rathflow-cli.svg)](https://pypi.org/project/rathflow-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/rathflow-cli.svg)](https://pypi.org/project/rathflow-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The RathFlow command line client. It talks to the RathFlow northbound REST API and
+covers sessions, memory, sandboxes, agents, assets, projects, billing and
+workflows.
+
+## Install
+
+```bash
+uv tool install rathflow-cli
+# or
+pipx install rathflow-cli
+# or
+pip install rathflow-cli
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Log in with your email and password (the password prompt does not echo).
+rathflow auth login -e you@example.com
+
+# Who am I, what can I reach.
+rathflow whoami
+
+# Pick a project scope; every later command carries it.
+rathflow project list
+rathflow project use <project_id>
+
+# Read something.
+rathflow session list
+```
+
+The default gateway is `https://rathflow.lynwe.com`. Point it elsewhere with
+`--base-url`, `RATHFLOW_BASE_URL`, or `rathflow config set base_url <url>`.
+
+## Commands
+
+| Group | What it covers |
+| --- | --- |
+| `auth` | log in / out, register, API keys (`keys`, `key-create`, `key-revoke`) |
+| `config` | local profiles (`list`, `show`, `set`, `use`) |
+| `org` | organizations, invitations |
+| `project` | projects, scope switching, project config, share links |
+| `session` | sessions, blocks, events |
+| `memory` | memory entries, search, commit tasks |
+| `sandbox` | sandboxes, exec, code, files, logs |
+| `agent` | agent definitions, versions, prompts, runs |
+| `asset` | assets, versions, credentials, publish |
+| `billing` | subscription, usage, invoices |
+| `workflow` | workflows |
+| `admin` | platform administration (platform admins only) |
+
+Two more entry points sit at the root:
+
+- `rathflow whoami` — identity, scope and reachable projects.
+- `rathflow api <Key>` — call any endpoint directly; `rathflow api --list` prints
+  the whole table. Streaming endpoints stream.
+
+Every group has `--help`, e.g. `rathflow session --help`.
+
+## Authentication
+
+`rathflow auth login` exchanges your email and password for a JWT, stored in the
+CLI config file (mode `0600`). The CLI sends it as a `Bearer` token and never
+touches cookies, so it is unaffected by the browser CSRF rules.
+
+For unattended use, issue a long-lived API key and pass it through the
+environment:
+
+```bash
+rathflow auth key-create          # prints the key once, right here
+export RATHFLOW_TOKEN=rf_...      # or: rathflow config set token rf_...
+```
+
+## Configuration
+
+Precedence, highest first: command-line flag > environment variable > active
+profile > built-in default. Profiles live in
+`~/.config/rathflow/config.json` (override the directory with
+`RATHFLOW_CONFIG_DIR`).
+
+| Variable | Meaning |
+| --- | --- |
+| `RATHFLOW_BASE_URL` | Gateway address |
+| `RATHFLOW_PROJECT` | Project scope |
+| `RATHFLOW_TOKEN` | Bearer token / API key |
+| `RATHFLOW_CONFIG_DIR` | Config directory |
+
+## Output
+
+- Default: human-readable tables.
+- `--json`: one stable JSON document, for scripts.
+- `--quiet` / `-q`: primary keys only.
+
+Exit codes are stable: `0` success, and non-zero for usage errors, API errors and
+remote command failures (a sandbox `exec` returns the remote exit code).
+
+## Proxies
+
+The CLI respects the standard proxy variables. One caveat: `httpx` cannot use a
+SOCKS proxy unless `socksio` is installed. If your environment sets
+`ALL_PROXY=socks://...` (some Clash setups do), install the extra or the CLI
+fails to start with `Unknown scheme for proxy URL`:
+
+```bash
+uv tool install 'rathflow-cli[socks]'
+# or clear it for this command only
+ALL_PROXY= rathflow whoami
+```
+
+## Development
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install -e .
+.venv/bin/rathflow --help
+.venv/bin/python -m rathflow_cli.selftest
+```
+
+`selftest` checks that no command hard-codes a URL and, when the upstream
+generated endpoint table is available (`RATHFLOW_ENDPOINTS_TS`), that
+`rathflow_cli/endpoints.py` still matches it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rathflow_cli-0.1.0/README.md

@@ -0,0 +1,133 @@
+# rathflow-cli
+
+[![PyPI](https://img.shields.io/pypi/v/rathflow-cli.svg)](https://pypi.org/project/rathflow-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/rathflow-cli.svg)](https://pypi.org/project/rathflow-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+The RathFlow command line client. It talks to the RathFlow northbound REST API and
+covers sessions, memory, sandboxes, agents, assets, projects, billing and
+workflows.
+
+## Install
+
+```bash
+uv tool install rathflow-cli
+# or
+pipx install rathflow-cli
+# or
+pip install rathflow-cli
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Log in with your email and password (the password prompt does not echo).
+rathflow auth login -e you@example.com
+
+# Who am I, what can I reach.
+rathflow whoami
+
+# Pick a project scope; every later command carries it.
+rathflow project list
+rathflow project use <project_id>
+
+# Read something.
+rathflow session list
+```
+
+The default gateway is `https://rathflow.lynwe.com`. Point it elsewhere with
+`--base-url`, `RATHFLOW_BASE_URL`, or `rathflow config set base_url <url>`.
+
+## Commands
+
+| Group | What it covers |
+| --- | --- |
+| `auth` | log in / out, register, API keys (`keys`, `key-create`, `key-revoke`) |
+| `config` | local profiles (`list`, `show`, `set`, `use`) |
+| `org` | organizations, invitations |
+| `project` | projects, scope switching, project config, share links |
+| `session` | sessions, blocks, events |
+| `memory` | memory entries, search, commit tasks |
+| `sandbox` | sandboxes, exec, code, files, logs |
+| `agent` | agent definitions, versions, prompts, runs |
+| `asset` | assets, versions, credentials, publish |
+| `billing` | subscription, usage, invoices |
+| `workflow` | workflows |
+| `admin` | platform administration (platform admins only) |
+
+Two more entry points sit at the root:
+
+- `rathflow whoami` — identity, scope and reachable projects.
+- `rathflow api <Key>` — call any endpoint directly; `rathflow api --list` prints
+  the whole table. Streaming endpoints stream.
+
+Every group has `--help`, e.g. `rathflow session --help`.
+
+## Authentication
+
+`rathflow auth login` exchanges your email and password for a JWT, stored in the
+CLI config file (mode `0600`). The CLI sends it as a `Bearer` token and never
+touches cookies, so it is unaffected by the browser CSRF rules.
+
+For unattended use, issue a long-lived API key and pass it through the
+environment:
+
+```bash
+rathflow auth key-create          # prints the key once, right here
+export RATHFLOW_TOKEN=rf_...      # or: rathflow config set token rf_...
+```
+
+## Configuration
+
+Precedence, highest first: command-line flag > environment variable > active
+profile > built-in default. Profiles live in
+`~/.config/rathflow/config.json` (override the directory with
+`RATHFLOW_CONFIG_DIR`).
+
+| Variable | Meaning |
+| --- | --- |
+| `RATHFLOW_BASE_URL` | Gateway address |
+| `RATHFLOW_PROJECT` | Project scope |
+| `RATHFLOW_TOKEN` | Bearer token / API key |
+| `RATHFLOW_CONFIG_DIR` | Config directory |
+
+## Output
+
+- Default: human-readable tables.
+- `--json`: one stable JSON document, for scripts.
+- `--quiet` / `-q`: primary keys only.
+
+Exit codes are stable: `0` success, and non-zero for usage errors, API errors and
+remote command failures (a sandbox `exec` returns the remote exit code).
+
+## Proxies
+
+The CLI respects the standard proxy variables. One caveat: `httpx` cannot use a
+SOCKS proxy unless `socksio` is installed. If your environment sets
+`ALL_PROXY=socks://...` (some Clash setups do), install the extra or the CLI
+fails to start with `Unknown scheme for proxy URL`:
+
+```bash
+uv tool install 'rathflow-cli[socks]'
+# or clear it for this command only
+ALL_PROXY= rathflow whoami
+```
+
+## Development
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install -e .
+.venv/bin/rathflow --help
+.venv/bin/python -m rathflow_cli.selftest
+```
+
+`selftest` checks that no command hard-codes a URL and, when the upstream
+generated endpoint table is available (`RATHFLOW_ENDPOINTS_TS`), that
+`rathflow_cli/endpoints.py` still matches it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rathflow_cli-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rathflow-cli"
+version = "0.1.0"
+description = "RathFlow command line client: sessions, memory, sandboxes, assets and billing over the RathFlow REST API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rath Team" }]
+keywords = ["rathflow", "cli", "agent", "sessions", "memory", "sandbox"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "httpx>=0.27",
+  "typer>=0.12",
+]
+
+[project.optional-dependencies]
+# 走 SOCKS 代理（ALL_PROXY=socks5://…）时需要，见 README「代理」一节。
+socks = ["httpx[socks]"]
+
+[project.urls]
+Homepage = "https://rathflow.lynwe.com/"
+Repository = "https://github.com/Rath-Team/rathflow-cli"
+Issues = "https://github.com/Rath-Team/rathflow-cli/issues"
+Changelog = "https://github.com/Rath-Team/rathflow-cli/blob/main/CHANGELOG.md"
+
+[project.scripts]
+rathflow = "rathflow_cli.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["rathflow_cli*"]

rathflow_cli-0.1.0/rathflow_cli/__init__.py

@@ -0,0 +1,6 @@
+"""RathFlow CLI —— RathFlow 北向 REST 的命令行客户端。
+
+安装：``uv tool install rathflow-cli``（或 ``pip install rathflow-cli``）。
+"""
+
+__version__ = "0.1.0"

rathflow_cli-0.1.0/rathflow_cli/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m rathflow_cli`（与 `rathflow` 入口点等价）。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

rathflow_cli-0.1.0/rathflow_cli/cli.py

@@ -0,0 +1,161 @@
+"""typer 根应用与全局选项。"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from . import __version__, errors, state as state_mod
+from .state import State
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="RathFlow 命令行客户端（JWT 登录；命令覆盖北向 REST 全部端点）。",
+)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"rathflow {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    profile: str = typer.Option(None, "--profile", "-p", help="配置档名（缺省 default）"),
+    base_url: str = typer.Option(None, "--base-url", help="gateway 地址（env RATHFLOW_BASE_URL）"),
+    project: str = typer.Option(None, "--project", help="项目作用域（env RATHFLOW_PROJECT）"),
+    json_out: bool = typer.Option(False, "--json", help="以 JSON 输出（脚本消费的稳定形态）"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="只输出主键"),
+    version: bool = typer.Option(
+        False, "--version", callback=_print_version, is_eager=True, help="显示版本并退出"
+    ),
+) -> None:
+    ctx.obj = state_mod.install(
+        State(
+            profile_name=profile,
+            base_url=base_url,
+            project=project,
+            json_out=json_out,
+            quiet=quiet,
+        )
+    )
+
+
+def _register() -> None:
+    from .commands import (
+        admin,
+        agent,
+        api_cmd,
+        asset,
+        auth_cmd,
+        billing,
+        config_cmd,
+        memory,
+        org,
+        project,
+        sandbox,
+        session,
+        workflow,
+    )
+
+    app.add_typer(auth_cmd.app, name="auth")
+    app.add_typer(config_cmd.app, name="config")
+    app.add_typer(org.app, name="org")
+    app.add_typer(project.app, name="project")
+    app.add_typer(session.app, name="session")
+    app.add_typer(memory.app, name="memory")
+    app.add_typer(sandbox.app, name="sandbox")
+    app.add_typer(agent.app, name="agent")
+    app.add_typer(asset.app, name="asset")
+    app.add_typer(billing.app, name="billing")
+    app.add_typer(workflow.app, name="workflow")
+    app.add_typer(admin.app, name="admin")
+
+    from .commands.auth_cmd import whoami
+
+    app.command("whoami", help="显示登录身份、作用域与可访问项目")(whoami)
+    # 逃生舱直接挂根：`rathflow api <Key>` 不必多打一层 `call`
+    app.command("api", help="任意端点调用（`rathflow api --list` 看全部）")(api_cmd.call)
+
+
+_register()
+
+
+# 可以挪到命令行最前的全局选项：前者是布尔旗标，后者各吃一个值。
+_HOIST_FLAGS = frozenset({"--json", "--quiet"})
+_HOIST_OPTS = frozenset({"--profile", "--base-url", "--project"})
+
+
+def _value_opts() -> set[str]:
+    """全 app 里「吃下一个词」的选项名 —— 用来判断挪旗标安不安全。
+
+    走 click 命令树而非 Typer 对象：Typer 只是注册表，click Group 是懒构建的。
+    """
+
+    def walk(cmd) -> set[str]:
+        found: set[str] = set()
+        for param in getattr(cmd, "params", []):
+            if getattr(param, "is_flag", False) or getattr(param, "count", False):
+                continue
+            found.update(getattr(param, "opts", []))
+        for sub in getattr(cmd, "commands", {}).values():
+            found |= walk(sub)
+        return found
+
+    return walk(typer.main.get_command(app))
+
+
+def _hoist_globals(argv: list[str]) -> list[str]:
+    """把写在命令**后面**的全局选项挪到最前。
+
+    click 只认组级选项出现在子命令之前，故 `rathflow project list --json` 会被
+    当成给 `list` 传参而报错。脚本里这个顺序太自然了，于是这里做一次改写：
+    只挪白名单里的选项，且前一个词不是吃值的选项（否则那个词是被当值用的，
+    例如 `--body --json` 里的 `--json` 是值，不能动）。
+    """
+    if len(argv) < 2:
+        return argv
+    value_opts = _value_opts()
+    head, tail = [argv[0]], []
+    hoisted: list[str] = []
+    idx = 1
+    while idx < len(argv):
+        tok = argv[idx]
+        prev = argv[idx - 1]
+        # 前一个词若是吃值的选项，本词就是它的值（click 也这么看），别动
+        safe = prev not in value_opts
+        if safe and tok in _HOIST_FLAGS:
+            hoisted.append(tok)
+            idx += 1
+            continue
+        if safe and tok in _HOIST_OPTS and idx + 1 < len(argv) and not argv[idx + 1].startswith("-"):
+            hoisted.extend([tok, argv[idx + 1]])
+            idx += 2
+            continue
+        tail.append(tok)
+        idx += 1
+    return head + hoisted + tail
+
+
+def main() -> None:
+    sys.argv = _hoist_globals(sys.argv)
+    try:
+        app()
+    except errors.UsageError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        sys.exit(errors.EXIT_USAGE)
+    except errors.ApiError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        for detail in exc.details:
+            print(f"  - {detail}", file=sys.stderr)
+        sys.exit(exc.exit_code)
+    except KeyboardInterrupt:  # pragma: no cover
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

rathflow_cli-0.1.0/rathflow_cli/commands/_common.py

@@ -0,0 +1,78 @@
+"""命令间共用的小工具（参数解析与请求体装配）。"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+
+from ..errors import UsageError
+
+PATH_OPT = typer.Option(None, "--path", help="路径参数 k=v，可重复（如 --path session_id=abc）")
+QUERY_OPT = typer.Option(None, "--query", help="查询参数 k=v，可重复")
+BODY_OPT = typer.Option(None, "--body", help="请求体 JSON 字面量")
+BODY_FILE_OPT = typer.Option(None, "--body-file", help="从文件读请求体 JSON（- 读 stdin）")
+PAGE_SIZE_OPT = typer.Option(None, "--page-size", help="分页大小")
+PAGE_TOKEN_OPT = typer.Option(None, "--page-token", help="分页游标")
+
+
+def pairs(items: list[str] | None) -> dict:
+    """['k=v', ...] → {k: v}；值里的 = 保留（只切第一个）。"""
+    out: dict[str, str] = {}
+    for item in items or []:
+        if "=" not in item:
+            raise UsageError(f"参数需形如 k=v，收到 {item!r}")
+        key, _, value = item.partition("=")
+        out[key.strip()] = value
+    return out
+
+
+def body_of(body: str | None, body_file: str | None) -> dict | None:
+    """装配请求体：字面量或文件（`-` = stdin）。两者互斥。"""
+    if body and body_file:
+        raise UsageError("--body 与 --body-file 不能同时用")
+    raw: str | None = None
+    if body_file:
+        raw = sys.stdin.read() if body_file == "-" else _read(body_file)
+    elif body:
+        raw = body
+    else:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise UsageError(f"请求体不是合法 JSON：{exc}") from None
+    if not isinstance(parsed, dict):
+        raise UsageError("请求体必须是 JSON 对象")
+    return parsed
+
+
+def _read(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        raise UsageError(f"读取请求体文件失败：{exc}") from None
+
+
+def pagination(page_size: int | None, page_token: str | None, extra: dict | None = None) -> dict:
+    """装配分页查询串（protojson 查询名用 proto 字段名 snake_case）。"""
+    query = dict(extra or {})
+    if page_size is not None:
+        query["page_size"] = page_size
+    if page_token:
+        query["page_token"] = page_token
+    return query
+
+
+def id_of(payload: dict, *keys: str) -> str:
+    """从响应里挑主键用于 -q 输出。"""
+    for key in keys:
+        value = (payload or {}).get(key)
+        if value:
+            return str(value)
+    return ""