@manyoars/oars 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# @manyoars/oars
|
|
2
|
+
|
|
3
|
+
The `oars` command line for Many Oars: sign in, deploy an agent, set its prices and make a test charge against it.
|
|
4
|
+
|
|
5
|
+
Node 24 or later. ESM only.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --global @manyoars/oars
|
|
11
|
+
oars --help
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Or run it once without installing:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npx @manyoars/oars <command>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Commands
|
|
21
|
+
|
|
22
|
+
`oars --help` lists the commands below (`oars help <command>` shows one command's flags). `oars --version` prints the version.
|
|
23
|
+
|
|
24
|
+
These flags work on every command:
|
|
25
|
+
|
|
26
|
+
- `--json` prints one JSON document on stdout instead of text (see below).
|
|
27
|
+
- `--api-url <url>` sets the platform API. The default is `OARS_API_URL`, else `https://api.manyoars.com`.
|
|
28
|
+
- `--idempotency-key <key>` is the base of every step's idempotency key (default: a fresh UUID). Rerun a failed command with the same key to resume.
|
|
29
|
+
|
|
30
|
+
### login
|
|
31
|
+
|
|
32
|
+
Signs in with your browser (RFC 8628 device flow) and stores the login.
|
|
33
|
+
|
|
34
|
+
- `--no-browser` prints the link and code without opening a browser.
|
|
35
|
+
- `--issuer-url <url>` is the Keycloak realm URL. The default is `OARS_ISSUER_URL`; with neither, the command exits 2.
|
|
36
|
+
|
|
37
|
+
### logout
|
|
38
|
+
|
|
39
|
+
Revokes the stored login and deletes it.
|
|
40
|
+
|
|
41
|
+
### deploy
|
|
42
|
+
|
|
43
|
+
Registers a workload, creates its prices and deploys it. Pass exactly one of `--template`, `--image` or `--manifest`. It stops at the first failed step and exits 9 (see below).
|
|
44
|
+
|
|
45
|
+
- `--image <ref>` deploys an image pinned by digest (`name@sha256:...`). Companions: `--name <name>`, `--port <n>` (default 8080), `--public`, `--cpu-millicores <n>` (default 250), `--memory-mib <n>` (default 256).
|
|
46
|
+
- `--manifest <file>` deploys a JSON workload manifest.
|
|
47
|
+
- `--always-on` keeps the public service running instead of idling. It works with `--image` and `--manifest`.
|
|
48
|
+
- `--template <id>` names a starter template. It exits 2 for now, because the public API does not list templates yet; companions `--price <ref>` (repeatable) and `--no-prices` wait with it.
|
|
49
|
+
- `--price-file <file>` is a JSON array of prices to create (with `--image` or `--manifest`).
|
|
50
|
+
- `--secret <NAME=value>` and `--secret-from-env <NAME>` add a workload secret; both repeat. Prefer `--secret-from-env`, which keeps the value out of your shell history.
|
|
51
|
+
- `--no-start` registers and prices the workload without deploying it.
|
|
52
|
+
|
|
53
|
+
The SDK key is shown once, so save it when `deploy` prints it.
|
|
54
|
+
|
|
55
|
+
### status
|
|
56
|
+
|
|
57
|
+
`oars status <workloadId>` shows a workload and its billing mode.
|
|
58
|
+
|
|
59
|
+
### test-charge
|
|
60
|
+
|
|
61
|
+
`oars test-charge <workloadId>` makes a TEST-mode charge against one of the workload's prices.
|
|
62
|
+
|
|
63
|
+
- `--price <ref>` picks the price. The default is the workload's only active price.
|
|
64
|
+
|
|
65
|
+
## The `--json` contract
|
|
66
|
+
|
|
67
|
+
With `--json`, stdout carries exactly one JSON document and a success exits 0.
|
|
68
|
+
|
|
69
|
+
- Success: `{"ok": true, ...}`. The rest depends on the command: `login` adds `email`; `deploy` adds `workloadId`, `prices`, `started`, `nextSteps` and, when this run minted it, `sdkKey`; `status` adds `workload` and `billingMode`; `test-charge` adds `chargeId` and `status`.
|
|
70
|
+
- Failure: `{"ok": false, "step": "...", "problem": {...}}`, where `problem` is the platform's problem document (`title`, `detail`, `code`, `actionUrl` when it sent them). A `deploy` that stopped after registering also carries `workloadId`, `rerun` and, if that run minted it, `sdkKey`.
|
|
71
|
+
|
|
72
|
+
Without `--json`, a failure prints the problem to stderr instead.
|
|
73
|
+
|
|
74
|
+
Exit codes:
|
|
75
|
+
|
|
76
|
+
| Code | Meaning |
|
|
77
|
+
|------|---------|
|
|
78
|
+
| 0 | success |
|
|
79
|
+
| 1 | unexpected error |
|
|
80
|
+
| 2 | usage error |
|
|
81
|
+
| 3 | authentication failed (login expired or denied, SDK key invalid, HTTP 401 or 403) |
|
|
82
|
+
| 4 | the platform rejected the input |
|
|
83
|
+
| 5 | conflict (an idempotency key or workload already used) |
|
|
84
|
+
| 6 | a person must act first (account, payment method, credits or compute cap) |
|
|
85
|
+
| 7 | rate limited |
|
|
86
|
+
| 8 | the platform could not be reached |
|
|
87
|
+
| 9 | `deploy` stopped part way; rerun the printed command to resume |
|
|
88
|
+
|
|
89
|
+
## Source
|
|
90
|
+
|
|
91
|
+
[github.com/manyoars/oars](https://github.com/manyoars/oars/tree/main/packages/cli), [Apache-2.0](https://github.com/manyoars/oars/blob/main/LICENSE).
|