@overaihq/cli 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # OverAI CLI
 
 Work on [OverAI](https://overai.com) workspaces from the command line: clone
-automations, web pages, functions, and tablespaces as local files, edit them
+authored resources as local files, edit them
 with any editor or AI coding agent, then push and deploy new versions.
 
 ## Install
@@ -12,17 +12,21 @@ npm install -g @overaihq/cli    # or: pnpm add -g @overaihq/cli
 overai update                   # later, update a global install in place
 ```
 
-Requires Node.js 22+.
-
 ## Quick start
 
 ```sh
-overai signin                   # browser sign-in
-overai clone <workspaceId>      # materialize a workspace as files
+overai signin                   # browser sign-in; choose your organization for SSO
+overai workspace list           # find a workspace id
+overai workspace show <id>      # read its name and overview
+overai workspace users <id>     # list users and direct/inherited roles
+overai create agent --workspace <id> --name "Support agent"
+overai clone <workspaceId>      # materialize resources and WORKSPACE.md
 # ...edit files...
 overai status                   # local edits + remote drift
 overai diff                     # what changed
 overai review                   # validation + best-practice review packet
+overai report bug "<details>"    # report broken or unexplained behavior
+overai report feature "<details>" # request a missing platform capability
 overai push -m "why"            # create new versions (not live yet)
 overai deploy                   # make the pushed versions live
 ```
@@ -32,6 +36,34 @@ Run `overai help` for the full command list, including function invocation,
 automation runs and per-node state, tablespace SQL (a psql-style REPL), and
 `overai dev` for live-previewing a web page from local files.
 
+Inside a clone, `workspace show` and `workspace users` infer the workspace id.
+`WORKSPACE.md` is the overview captured when the clone is created; use
+`workspace show` when you need the current server value.
+
+`overai create` supports workspaces, automations, functions, web pages,
+printable pages, agents, integrations, TableSpaces, data streams, data files,
+and action runners. `resource show|update <id>` handles their mutable metadata.
+Versioned automations, functions, pages, and agents are edited through
+clone/push/deploy. Runtime commands include `agent generate`, `data-stream
+append|query`, `data-file upload|download|head`, `integration configure|config`,
+and `printable-page render`; `overai help` shows their arguments.
+
+## Passing queries, JSON, and scripts
+
+Arguments that carry a whole document rather than a scalar also accept `@<file>`
+to read it from disk, or `@-` to read it from stdin:
+
+```sh
+overai graphql -q @mutation.graphql --variables @vars.json
+overai sql <tableSpaceId> @report.sql
+overai runner run <runnerId> --interpreter powershell --code @collect.ps1
+```
+
+Prefer this for anything long or quote-heavy. An inline value is parsed by your
+shell first, and a single apostrophe inside it closes the quoting — the rest of
+the blob is then read as shell source, which mangles it silently. Write `@@` to
+send a literal value that starts with `@`.
+
 ## For AI agents
 
 The CLI bundles its own guidance — no extra setup files needed. Point your
@@ -41,3 +73,8 @@ agent at a cloned workspace and have it run:
 overai best-practices           # platform + per-resource-type guides
 overai review                   # before every push
 ```
+
+When platform behavior blocks progress, agents can send detailed feedback with
+`overai report bug -` or `overai report feature -` and the report body on stdin.
+Reports include CLI, runtime, organization, and cloned-workspace identifiers,
+but never files, diffs, environment variables, paths, or command history.