@theopenapps/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Open Apps, Inc.
+
+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.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @theopenapps/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`openapps` reads the [OpenApps](https://theopenapps.com) API from a terminal: what is listed, ranked, featured and launched in the ChatGPT, Claude, Cursor, Grok Bot, Perplexity and Muse app stores, and the tools of the MCP servers their apps link to. Public reads need no account.
+
+```sh
+npx @theopenapps/cli charts get claude popularity
+npm install -g @theopenapps/cli
+openapps changes list chatgpt --since=-7d --types rank_move,chart_enter
+openapps apps search context7 --store cursor --format csv
+openapps apps metrics claude:plugin_01E5qTAcHfq3r1UJ8Zxgzjae --json
+```
+
+Commands are `openapps <resource> <verb>`, one per API operation. `openapps --help` lists them, and `openapps <resource> <verb> --help` shows a command's arguments, flags and examples. Output is JSON when stdout is not a terminal and a table when it is; `--format json|table|csv|md` and `--fields a,b` choose otherwise. Inputs are checked before any request, and unknown enum values print the allowed ones.
+
+Exit codes: 0 ok, 1 other error, 2 usage or invalid input, 3 not found, 4 rate-limited.
+
+`openapps agent-context` prints the JSON an agent needs to use the API, and `openapps mcp-url` prints the MCP server URL. `--base-url` or `OPENAPPS_BASE_URL` points the CLI at another deployment, such as `http://localhost:8788/v1` under `wrangler dev`.
+
+## Signing in
+
+Without an account the CLI reads what a signed-out visitor sees: the United States and the top rows of each list, at 60 calls a minute. A free account adds every country and deeper lists, and Pro shows everything.
+
+```sh
+openapps auth login     # opens your browser to sign in and approve the CLI
+openapps auth status    # which credential calls use
+openapps auth logout    # revokes this computer's sign-in
+```
+
+`auth login` signs in with OAuth. It opens your browser, you approve the OpenApps CLI, and the browser returns to the CLI on `127.0.0.1`. The CLI keeps the tokens in `~/.config/openapps/auth.json` (or `$XDG_CONFIG_HOME/openapps`, `%APPDATA%\openapps` on Windows, `OPENAPPS_CONFIG_DIR` to choose), readable by your user alone, and sends them only to the deployment that issued them. Access renews itself for 30 days, then the CLI asks you to sign in again. `--no-browser` prints the link without opening it. The account page's Connected apps lists the sign-in and can revoke it.
+
+On a computer without a browser, such as a server or CI, create a key in your [OpenApps account](https://theopenapps.com/account/keys) and set `OPENAPPS_API_KEY`. A key wins over a sign-in. The CLI sends it as a bearer header, follows no redirects, and sends it only to `https://theopenapps.com`; set `OPENAPPS_AUTH_ORIGIN` to another deployment's origin to send it there. Keys expire after 90 days and can be revoked from the account page.
+
+## Releases
+
+Every deploy of OpenApps that changes the CLI or the API contract it was built from publishes a new patch version to npm (`cli/release.ts`). A CLI built against an older contract still works and prints a one-line notice to update.