code.oscarkilo.com/okg #fb141023c838ce54a189ef5270cfb3b60ba24412

Hash:

fb141023c838ce54a189ef5270cfb3b60ba24412

Author:

Date:

Thu Jun 4 20:41:46 2026 -0400

Message:

okg: bootstrap //okg/who; add `okg group list` New //okg/who subpackage is the world-public side of the //who HTTP API. It embeds //okg/internal/rest for the shared host/api-key/JSON-marshaling plumbing — no duplication with //okg/klee. Today it ships HTTPClient + Group + ListGroups; more methods (create, join, leave, members, delete; authz set/delete) land in follow-up commits, then //clients/who gets refactored to dot-import this package and drop its own duplicate types. The struct here is named HTTPClient (not Client) so the eventual `import . "oscarkilo.com/okg/who"` inside //clients/who doesn't collide with that package's existing Client interface — see the package doc. `okg group list` is the first user: fetches groups visible to the caller, tabwriter-prints USERNAME / FULL NAME / OWNER, or --json for the raw payload.

diff --git a/README.md b/README.md
index bdf96e5..b936a71 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,8 @@ okg pr reopen NUMBER

okg auth login [--key KEY] [--host HOST]

+okg group list [--json]
+
okg embed [--model NAME] [--dims N] [--full-path]
(reads stdin → vectors on stdout)
okg one [--model NAME] [--system-file FILE] \
diff --git a/group.go b/group.go
new file mode 100644
index 0000000..736a132
--- /dev/null
+++ b/group.go
@@ -0,0 +1,63 @@
+package main
+
+import "encoding/json"
+import "flag"
+import "fmt"
+import "os"
+import "text/tabwriter"
+
+import "oscarkilo.com/okg/who"
+
+func runGroup(args []string) error {
+ if len(args) == 0 {
+ return fmt.Errorf(
+ "usage: okg group SUBCOMMAND ... (try `okg --help`)")
+ }
+ switch args[0] {
+ case "list":
+ return runGroupList(args[1:])
+ default:
+ return fmt.Errorf(
+ "unknown group subcommand: %s", args[0])
+ }
+}
+
+func runGroupList(args []string) error {
+ fs := flag.NewFlagSet("group list", flag.ContinueOnError)
+ asJSON := fs.Bool("json", false, "output raw JSON")
+ if err := fs.Parse(args); err != nil {
+ return err
+ }
+
+ cfg, err := loadConfig()
+ if err != nil {
+ return err
+ }
+ if cfg.ApiKey == "" {
+ return fmt.Errorf(
+ "no API key — run `okg auth login --key sk-...`")
+ }
+
+ c := who.NewHTTPClient(cfg.Host, cfg.ApiKey)
+ groups, err := c.ListGroups()
+ if err != nil {
+ return err
+ }
+
+ if *asJSON {
+ buf, err := json.MarshalIndent(groups, "", " ")
+ if err != nil {
+ return err
+ }
+ fmt.Println(string(buf))
+ return nil
+ }
+
+ tw := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)
+ fmt.Fprintln(tw, "USERNAME\tFULL NAME\tOWNER")
+ for _, g := range groups {
+ fmt.Fprintf(tw, "%s\t%s\t%s\n",
+ g.Username, g.Name, g.OwnerUsername)
+ }
+ return tw.Flush()
+}
diff --git a/main.go b/main.go
index 116bb98..24f98d8 100644
--- a/main.go
+++ b/main.go
@@ -22,6 +22,8 @@ func main() {
err = runEmbed(args[1:])
case "one":
err = runOne(args[1:])
+ case "group":
+ err = runGroup(args[1:])
case "help", "--help", "-h":
printUsage()
return
@@ -53,6 +55,10 @@ GIT REPOS
okg repo create NAME
--reader USER grant read to USER (default: anyone)

+GROUPS
+ okg group list
+ --json output raw JSON
+
PULL REQUESTS
okg pr list
--state STATE open or closed (default: open)
@@ -115,6 +121,9 @@ EXAMPLES
okg repo list
okg repo create my-new-repo

+ Groups
+ okg group list
+
Pull requests
okg pr list --state open
okg pr view 42
diff --git a/who/who.go b/who/who.go
new file mode 100644
index 0000000..e04fc78
--- /dev/null
+++ b/who/who.go
@@ -0,0 +1,48 @@
+// Package who is the public HTTP client for OscarKilo's //who
+// service. It is the world-public side of //who, used by
+// `okg` and any other tool that talks to oscarkilo.com over
+// the network.
+//
+// //clients/who (intra-cluster, has the in-process MockClient,
+// the /internal/* calls, the dev/prod factory) will eventually
+// import this package via `import . "oscarkilo.com/okg/who"`
+// so the two share types and request paths. To make that dot
+// import work, the struct here is named HTTPClient — leaving
+// the unqualified `Client` name free for //clients/who's
+// existing interface.
+package who
+
+import "oscarkilo.com/okg/internal/rest"
+
+// HTTPClient talks to a //who server over HTTPS. Embeds the
+// shared rest helpers; who-specific methods live below.
+type HTTPClient struct {
+ *rest.Client
+}
+
+func NewHTTPClient(host, apiKey string) *HTTPClient {
+ return &HTTPClient{Client: rest.NewClient(host, apiKey)}
+}
+
+// Group describes a //who group (a named entity with members).
+// Mirrors the listedGroup shape in //who/server/groups_list.go.
+type Group struct {
+ Owid string `json:"owid"`
+ Username string `json:"username"`
+ Name string `json:"name"`
+ OwnerOwid string `json:"owner_owid"`
+ OwnerUsername string `json:"owner_username"`
+}
+
+type listGroupsResponse struct {
+ Groups []Group `json:"groups"`
+}
+
+// ListGroups returns the groups visible to the caller.
+func (c *HTTPClient) ListGroups() ([]Group, error) {
+ var res listGroupsResponse
+ if err := c.GetJSON("/groups/list", &res); err != nil {
+ return nil, err
+ }
+ return res.Groups, nil
+}
diff --git a/who/who_test.go b/who/who_test.go
new file mode 100644
index 0000000..b62742a
--- /dev/null
+++ b/who/who_test.go
@@ -0,0 +1,72 @@
+package who
+
+import "encoding/json"
+import "net/http"
+import "net/http/httptest"
+import "testing"
+
+func TestListGroups(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(
+ func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/groups/list" {
+ t.Errorf("path: got %q, want /groups/list",
+ r.URL.Path)
+ }
+ if r.Header.Get("Authorization") !=
+ "Bearer test-key" {
+ t.Errorf("Authorization: got %q",
+ r.Header.Get("Authorization"))
+ }
+ w.Header().Set(
+ "Content-Type", "application/json")
+ json.NewEncoder(w).Encode(listGroupsResponse{
+ Groups: []Group{
+ {
+ Username: "team",
+ Name: "Team",
+ OwnerUsername: "alice",
+ },
+ {
+ Username: "admins",
+ Name: "Admins",
+ OwnerUsername: "alice",
+ },
+ },
+ })
+ }))
+ defer srv.Close()
+
+ c := NewHTTPClient(srv.URL, "test-key")
+ groups, err := c.ListGroups()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(groups) != 2 {
+ t.Fatalf("len: got %d, want 2", len(groups))
+ }
+ if groups[0].Username != "team" {
+ t.Errorf(
+ "groups[0].Username: got %q, want team",
+ groups[0].Username)
+ }
+ if groups[1].OwnerUsername != "alice" {
+ t.Errorf(
+ "groups[1].OwnerUsername: got %q, want alice",
+ groups[1].OwnerUsername)
+ }
+}
+
+func TestListGroupsHTTPError(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(
+ func(w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(401)
+ w.Write([]byte("not authenticated"))
+ }))
+ defer srv.Close()
+
+ c := NewHTTPClient(srv.URL, "bad-key")
+ _, err := c.ListGroups()
+ if err == nil {
+ t.Fatal("want error on 401, got nil")
+ }
+}

# okg — Oscar Kilo Goodness

A command-line tool that bundles Oscar Kilo's externally usable

services into one binary. Today: git ops against

[klee](https://code.oscarkilo.com), and LLM embeddings against

[klex](https://oscarkilo.com/klex). More LLM utilities (`one`,

`exemplary`) coming as the legacy `klex-git` binaries fold in.

Designed for both humans and AI agents (Claude, OpenClaw) to

use directly from the command line.

## Install

```bash

go install oscarkilo.com/okg@latest

```

Or build from source:

```bash

git clone https://code.oscarkilo.com/okg

cd okg && go build .

```

## Setup

By default okg talks to the production klee host

(`https://code.oscarkilo.com`); the only setup you need is your

API key. `okg auth login` saves it to

`~/.config/okg/config.json`.

```bash

# Non-interactive (for agents and scripts).

okg auth login --key sk-...

cat ~/.klex.key | okg auth login # equivalent, ps-safe

# Interactive (prompts for host then key).

okg auth login

```

Override the host for dev/local work with `--host` on `auth login`.

## Commands

```

okg repo list

okg pr list [--state open|closed]

okg pr create --head BRANCH [--base master] --title TITLE [--body BODY]

okg pr view NUMBER

okg pr diff NUMBER

okg pr comment NUMBER --body BODY [--approve | --request-changes]

okg pr merge NUMBER

okg pr close NUMBER

okg pr reopen NUMBER

okg auth login [--key KEY] [--host HOST]

okg group list [--json]

okg embed [--model NAME] [--dims N] [--full-path]

(reads stdin → vectors on stdout)

okg one [--model NAME] [--system-file FILE] \

[--prompt-file FILE] [--attach FILE] \

[--format text|json|jsonindent] [--fast-fail]

(reads stdin as a JSON MessagesRequest)

```

### Coming next

- `okg exemplary` — few-shot batch runner (from

`klex-git/exemplary`).

Once that lands, the standalone `klex-git` binaries are

deprecated.

### Flags

- `--repo REPO` overrides auto-detected repo name

(normally parsed from `git remote get-url origin`)

- `--json` outputs raw JSON for any command

- `OKG_REPO` env var also overrides repo detection

## Repo Detection

Like `gh`, okg detects the repo from the current directory's

git remote:

```

git remote get-url origin

→ https://code.oscarkilo.com/widget.git

→ repo = "widget"

```

## Dependencies

- `oscarkilo.com/klex-git` for the LLM API client (transitional;

to be folded in once all `klex-git` binaries have moved here).

- Otherwise Go standard library only.

package main

import "encoding/json"

import "flag"

import "fmt"

import "os"

import "text/tabwriter"

import "oscarkilo.com/okg/who"

func runGroup(args []string) error {

if len(args) == 0 {

return fmt.Errorf(

"usage: okg group SUBCOMMAND ... (try `okg --help`)")

}

switch args[0] {

case "list":

return runGroupList(args[1:])

default:

return fmt.Errorf(

"unknown group subcommand: %s", args[0])

}

func runGroupList(args []string) error {

fs := flag.NewFlagSet("group list", flag.ContinueOnError)

asJSON := fs.Bool("json", false, "output raw JSON")

if err := fs.Parse(args); err != nil {

return err

}

cfg, err := loadConfig()

if err != nil {

return err

}

if cfg.ApiKey == "" {

return fmt.Errorf(

"no API key — run `okg auth login --key sk-...`")

}

c := who.NewHTTPClient(cfg.Host, cfg.ApiKey)

groups, err := c.ListGroups()

if err != nil {

return err

}

if *asJSON {

buf, err := json.MarshalIndent(groups, "", " ")

if err != nil {

return err

}

fmt.Println(string(buf))

return nil

}

tw := tabwriter.NewWriter(os.Stdout, 0, 2, 2, ' ', 0)

fmt.Fprintln(tw, "USERNAME\tFULL NAME\tOWNER")

for _, g := range groups {

fmt.Fprintf(tw, "%s\t%s\t%s\n",

g.Username, g.Name, g.OwnerUsername)

}

return tw.Flush()

}

package main

import "fmt"

import "os"

func main() {

args := os.Args[1:]

if len(args) == 0 {

printUsage()

os.Exit(1)

}

var err error

switch args[0] {

case "pr":

err = runPR(args[1:])

case "repo":

err = runRepo(args[1:])

case "auth":

err = runAuth(args[1:])

case "embed":

err = runEmbed(args[1:])

case "one":

err = runOne(args[1:])

case "group":

err = runGroup(args[1:])

case "help", "--help", "-h":

printUsage()

return

default:

fmt.Fprintf(os.Stderr, "unknown command: %s\n", args[0])

printUsage()

os.Exit(1)

}

if err != nil {

fmt.Fprintf(os.Stderr, "error: %v\n", err)

os.Exit(1)

}

func printUsage() {

fmt.Fprintf(os.Stderr, `NAME

okg — Oscar Kilo Goodness

SETUP

okg auth login

--key KEY API key (also accepted via stdin)

--host HOST klee host (default: production)

GIT REPOS

okg repo list

--json output raw JSON

okg repo create NAME

--reader USER grant read to USER (default: anyone)

GROUPS

okg group list

--json output raw JSON

PULL REQUESTS

okg pr list

--state STATE open or closed (default: open)

--json output raw JSON

okg pr create

--head BRANCH source branch

--base BRANCH target branch (default: master)

--title TITLE PR title

--body BODY PR body (optional)

--json output raw JSON

okg pr view NUMBER

--json output raw JSON

okg pr diff NUMBER

okg pr comment NUMBER

--body BODY comment body

--approve also approve the PR

--request-changes also request changes

okg pr merge NUMBER

--json output raw JSON

okg pr close NUMBER

--json output raw JSON

okg pr reopen NUMBER

--json output raw JSON

ARTIFICIAL INTELLIGENCE

okg embed

--model NAME embedding model

(default: openai:text-embedding-3-small)

--dims N number of dimensions (default: 1536)

--full-path one vector per prefix of input

(reads stdin; writes vectors to stdout, one per line)

100

okg one

101

okg one

--model NAME override .Model in the request

102

--model NAME override .Model in the request

--system-file FILE override .System with contents of FILE

103

--system-file FILE override .System with contents of FILE

--prompt-file FILE append FILE as a user prompt

104

--prompt-file FILE append FILE as a user prompt

--attach FILE attach an image or PDF to the prompt

105

--attach FILE attach an image or PDF to the prompt

100

--format FORMAT text | json | jsonindent (default: text)

106

--format FORMAT text | json | jsonindent (default: text)

101

--fast-fail preflight attachment MIME (default: on)

107

--fast-fail preflight attachment MIME (default: on)

102

(reads stdin as a JSON MessagesRequest; flags override

108

(reads stdin as a JSON MessagesRequest; flags override

103

its fields)

109

its fields)

104

110

105

GLOBAL FLAGS

111

GLOBAL FLAGS

106

--repo REPO override auto-detected repo name

112

--repo REPO override auto-detected repo name

107

--json output raw JSON (where applicable)

113

--json output raw JSON (where applicable)

108

114

109

EXAMPLES

115

EXAMPLES

110

Setup

116

Setup

111

okg auth login --key sk-...

117

okg auth login --key sk-...

112

cat ~/.klex.key | okg auth login

118

cat ~/.klex.key | okg auth login

113

119

114

Git repos

120

Git repos

115

okg repo list

121

okg repo list

116

okg repo create my-new-repo

122

okg repo create my-new-repo

117

123

124

Groups

125

okg group list

126

118

Pull requests

127

Pull requests

119

okg pr list --state open

128

okg pr list --state open

120

okg pr view 42

129

okg pr view 42

121

okg pr comment 42 --body 'LGTM' --approve

130

okg pr comment 42 --body 'LGTM' --approve

122

131

123

Artificial intelligence

132

Artificial intelligence

124

echo 'hello world' | okg embed --dims 384

133

echo 'hello world' | okg embed --dims 384

125

echo Hello? > /tmp/q.txt && \

134

echo Hello? > /tmp/q.txt && \

126

okg one --model openai:gpt-4o-mini --prompt-file /tmp/q.txt

135

okg one --model openai:gpt-4o-mini --prompt-file /tmp/q.txt

127

136

128

}

137

}

// Package who is the public HTTP client for OscarKilo's //who

// service. It is the world-public side of //who, used by

// `okg` and any other tool that talks to oscarkilo.com over

// the network.

// //clients/who (intra-cluster, has the in-process MockClient,

// the /internal/* calls, the dev/prod factory) will eventually

// import this package via `import . "oscarkilo.com/okg/who"`

// so the two share types and request paths. To make that dot

// import work, the struct here is named HTTPClient — leaving

// the unqualified `Client` name free for //clients/who's

// existing interface.

package who

import "oscarkilo.com/okg/internal/rest"

// HTTPClient talks to a //who server over HTTPS. Embeds the

// shared rest helpers; who-specific methods live below.

type HTTPClient struct {

*rest.Client

}

func NewHTTPClient(host, apiKey string) *HTTPClient {

return &HTTPClient{Client: rest.NewClient(host, apiKey)}

}

// Group describes a //who group (a named entity with members).

// Mirrors the listedGroup shape in //who/server/groups_list.go.

type Group struct {

Owid string `json:"owid"`

Username string `json:"username"`

Name string `json:"name"`

OwnerOwid string `json:"owner_owid"`

OwnerUsername string `json:"owner_username"`

}

type listGroupsResponse struct {

Groups []Group `json:"groups"`

}

// ListGroups returns the groups visible to the caller.

func (c *HTTPClient) ListGroups() ([]Group, error) {

var res listGroupsResponse

if err := c.GetJSON("/groups/list", &res); err != nil {

return nil, err

}

return res.Groups, nil

}

package who

import "encoding/json"

import "net/http"

import "net/http/httptest"

import "testing"

func TestListGroups(t *testing.T) {

srv := httptest.NewServer(http.HandlerFunc(

func(w http.ResponseWriter, r *http.Request) {

if r.URL.Path != "/groups/list" {

t.Errorf("path: got %q, want /groups/list",

r.URL.Path)

}

if r.Header.Get("Authorization") !=

"Bearer test-key" {

t.Errorf("Authorization: got %q",

r.Header.Get("Authorization"))

}

w.Header().Set(

"Content-Type", "application/json")

json.NewEncoder(w).Encode(listGroupsResponse{

Groups: []Group{

{

Username: "team",

Name: "Team",

OwnerUsername: "alice",

{

Username: "admins",

Name: "Admins",

OwnerUsername: "alice",

})

}))

defer srv.Close()

c := NewHTTPClient(srv.URL, "test-key")

groups, err := c.ListGroups()

if err != nil {

t.Fatal(err)

}

if len(groups) != 2 {

t.Fatalf("len: got %d, want 2", len(groups))

}

if groups[0].Username != "team" {

t.Errorf(

"groups[0].Username: got %q, want team",

groups[0].Username)

}

if groups[1].OwnerUsername != "alice" {

t.Errorf(

"groups[1].OwnerUsername: got %q, want alice",

groups[1].OwnerUsername)

}

func TestListGroupsHTTPError(t *testing.T) {

srv := httptest.NewServer(http.HandlerFunc(

func(w http.ResponseWriter, r *http.Request) {

w.WriteHeader(401)

w.Write([]byte("not authenticated"))

}))

defer srv.Close()

c := NewHTTPClient(srv.URL, "bad-key")

_, err := c.ListGroups()

if err == nil {

t.Fatal("want error on 401, got nil")

}