@velven/cli 0.0.1 → 0.1.0
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 +110 -2
- package/dist/velven.js +1353 -0
- package/package.json +32 -7
- package/bin/velven.js +0 -2
package/README.md
CHANGED
|
@@ -1,5 +1,113 @@
|
|
|
1
1
|
# @velven/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Publish a folder to [Velven](https://velven.ai), the community marketplace for spaces built with AI. Velven hosts the files
|
|
4
|
+
and gives you a private preview link; `--prod` checks the version for safety, then puts it live on its own Velven page
|
|
5
|
+
with the SDK added.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
```sh
|
|
8
|
+
npx @velven/cli login
|
|
9
|
+
npx @velven/cli publish ./dist # a private preview, link printed
|
|
10
|
+
npx @velven/cli publish ./dist --prod # live once Velven's check passes
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Or install it: `npm install -g @velven/cli`, then run `velven`. Node 20 or later. No dependencies.
|
|
14
|
+
|
|
15
|
+
## velven.json
|
|
16
|
+
|
|
17
|
+
The listing comes from `velven.json` in the folder you publish. It stays on your machine; it is never uploaded, and neither is a `velven.json` in any folder below, whatever its case.
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"title": "Star Hop",
|
|
22
|
+
"type": "game",
|
|
23
|
+
"devices": ["desktop", "mobile"],
|
|
24
|
+
"description": "Hop between stars before the light runs out.",
|
|
25
|
+
"engine": "three.js"
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Required: `title`, `type` (`game`, `world`, `tool` or `wonder`) and `devices` (`desktop`, `mobile`, `vr`). When one is
|
|
30
|
+
missing, `velven publish` asks for it in a terminal and saves your answer into `velven.json`; anywhere else it stops
|
|
31
|
+
and names each missing field.
|
|
32
|
+
|
|
33
|
+
Optional: `description`, `engine`, `ai_tools`, `models`, `how_made`, `source_url`, and for hosting:
|
|
34
|
+
|
|
35
|
+
| Key | What it does |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `entry` | The page to open, when it is not `index.html` |
|
|
38
|
+
| `spa` | `true` serves the entry page for any path without a file (client-side routing) |
|
|
39
|
+
| `sdk` | `false` stops Velven adding the SDK's script tag (set it when you bundle `@velven/sdk` yourself) |
|
|
40
|
+
| `start` | How to get past a start screen for the safety check: `{ "click": "Play" }`, `{ "click": [x, y] }` or `{ "key": "Space" }` |
|
|
41
|
+
| `boards`, `achievements`, `stats`, `toasts` | Leaderboards, achievements and stats, declared as in the SDK docs |
|
|
42
|
+
| `space` | Written by the first publish; later publishes update that space |
|
|
43
|
+
| `claim` | Written by a publish without an account; it updates the unlisted page until you claim it |
|
|
44
|
+
|
|
45
|
+
A `.velvenignore` file leaves files out: one pattern a line, `*`, `**` and `?`, `folder/` for folders, `#` comments.
|
|
46
|
+
Dotfiles, `node_modules` and every `velven.json` are always left out, in any case, as is a name that ends in a dot or a space or holds `:` or `~` (the CLI names each such file);
|
|
47
|
+
`velven dev` serves by the same rule, `.velvenignore` included, and a path only in the letter case the folder spells it, as the live version
|
|
48
|
+
looks paths up (`Assets/Hero.png` does not open `assets/hero.png`). A link to a file or folder inside the folder is followed (a folder link's files go up under the
|
|
49
|
+
link's name); a link outside the folder, to one of those, or back up to a folder it sits in is left out, and the CLI names each
|
|
50
|
+
link it leaves out. A version holds at most 100 MB and 2,000 files.
|
|
51
|
+
|
|
52
|
+
## Commands
|
|
53
|
+
|
|
54
|
+
| Command | What it does |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `velven login` | Sign in: shows a code and opens velven.ai to approve it |
|
|
57
|
+
| `velven logout` | Forget this computer's sign-in |
|
|
58
|
+
| `velven whoami` | Who you are signed in as |
|
|
59
|
+
| `velven publish [dir]` | Upload the folder (only files Velven does not already have) as a private preview; with `--prod`, Velven checks it and puts it live |
|
|
60
|
+
| `velven versions` | The space's versions; `*` marks the live one |
|
|
61
|
+
| `velven rollback [version]` | Put an earlier version live again (asks which when you leave it out) |
|
|
62
|
+
| `velven dev [dir]` | Serve the folder on `localhost` and play it on Velven, with scores and saves going to the sandbox |
|
|
63
|
+
| `velven reset` | Delete the space's sandbox data: `--scores --saves --achievements --content --rooms` (default all), `--player <handle>` |
|
|
64
|
+
|
|
65
|
+
`velven publish` options:
|
|
66
|
+
|
|
67
|
+
- Without `--prod`: a private preview. The link works for 24 hours; scores and saves made there go to the sandbox.
|
|
68
|
+
- `--prod`: go live on the space's Velven page once Velven's safety check passes.
|
|
69
|
+
- `--wait`: wait here for the preview link, or with `--prod` for the check's verdict. A refused version prints the
|
|
70
|
+
reason; a version the check could not judge prints what it saw, and a start hint usually fixes it. Either way you can
|
|
71
|
+
ask for a review from the link printed.
|
|
72
|
+
- `--title`, `--type`, `--devices desktop,mobile`, `--description`, `--engine`: override `velven.json` for this run only.
|
|
73
|
+
- `--yes`: never ask for missing fields; fail naming them instead.
|
|
74
|
+
- `--json`: print one JSON object, for scripts and agents (also on `whoami` and `versions`).
|
|
75
|
+
|
|
76
|
+
`versions`, `rollback` and `reset` act on the space `velven.json` in the current folder names; `--space <slug>` picks another.
|
|
77
|
+
|
|
78
|
+
## Without an account
|
|
79
|
+
|
|
80
|
+
`velven publish` works before you sign in. It makes an **unlisted page** on Velven: live once it passes Velven's check,
|
|
81
|
+
with every SDK feature, but not listed anywhere on Velven until you claim it. The CLI prints the page's address, a claim
|
|
82
|
+
token and a claim link, and saves the token in `velven.json` as `"claim"`, so publishing again from the folder updates
|
|
83
|
+
the same page. When `velven.json` cannot be written (read-only, or a folder you cannot write to), the CLI says so, prints
|
|
84
|
+
what to put in it (the token, or signed in the slug as `"space"`) and goes on with the publish; `--json` carries that
|
|
85
|
+
sentence as `notSaved`. An unclaimed page is deleted 7 days after its first publish.
|
|
86
|
+
|
|
87
|
+
To claim it, open the claim link, or run `velven login` and publish again from the folder: the page becomes yours, goes
|
|
88
|
+
on Velven, and `"claim"` in `velven.json` is replaced by `"space"`. Claimed it in the browser? Run `velven login`
|
|
89
|
+
before publishing again: signed out, the claimed page's token exits 3 (`claim_spent`); claimed while the CLI uploads,
|
|
90
|
+
the version was never finished, so it exits 3 saying to run `velven login` and publish again; claimed while it waits
|
|
91
|
+
with `--wait`, it exits 3 with the space's Files tab link, where the check goes on. Without an account a version
|
|
92
|
+
holds at most 50 MB and 1,000 files, and `--prod` needs you to sign in. By publishing you agree to Velven's Terms: https://velven.ai/terms
|
|
93
|
+
|
|
94
|
+
## In CI
|
|
95
|
+
|
|
96
|
+
Set `VELVEN_TOKEN` to a token from `velven login` (in `~/.config/velven/auth.json`) and run
|
|
97
|
+
`velven publish --prod --yes --wait`. The token takes precedence over a saved sign-in. Revoke tokens in your Velven settings.
|
|
98
|
+
|
|
99
|
+
`VELVEN_API` points the CLI at another Velven, such as `http://localhost:3000` when running Velven itself locally.
|
|
100
|
+
|
|
101
|
+
## Exit codes
|
|
102
|
+
|
|
103
|
+
| Code | Meaning |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| 0 | Done |
|
|
106
|
+
| 1 | Failed: the network, a server error, a failed upload, or cancelled |
|
|
107
|
+
| 2 | A mistake in the command or in `velven.json`, such as a missing field |
|
|
108
|
+
| 3 | Not signed in (or the token was refused) for something that needs an account, such as `--prod` |
|
|
109
|
+
| 4 | Refused by Velven: not your space, too large, too many files, not found |
|
|
110
|
+
| 5 | Rate limited: try again later |
|
|
111
|
+
| 6 | With `--wait`: the safety check refused the version or could not judge it |
|
|
112
|
+
|
|
113
|
+
Docs: https://velven.ai/docs
|