@palettelab/cli 0.3.22 → 0.3.23
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 +172 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -21,6 +21,178 @@ npx @palettelab/cli <command>
|
|
|
21
21
|
pltt <command>
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
+
## Quick Start: Build And Test A Palette App
|
|
25
|
+
|
|
26
|
+
Use this flow when a developer wants to create an app, run it locally, then test
|
|
27
|
+
it inside the real Palette OS without Docker.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx --yes @palettelab/cli@latest init simple-todo --template database
|
|
31
|
+
cd simple-todo
|
|
32
|
+
npm install
|
|
33
|
+
npx --yes @palettelab/cli@latest dev
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`pltt dev` runs the local SDK simulator. It is the fastest loop for frontend,
|
|
37
|
+
backend, manifest, SDK hooks, and local database checks. It does not require
|
|
38
|
+
Docker and does not publish anything to the platform.
|
|
39
|
+
|
|
40
|
+
When the app is ready to test with real Palette OS services, configure a hosted
|
|
41
|
+
sandbox environment and run:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx --yes @palettelab/cli@latest login \
|
|
45
|
+
--env staging \
|
|
46
|
+
--url https://YOUR-PALETTE-STAGING-URL \
|
|
47
|
+
--token pltt_xxxxx
|
|
48
|
+
|
|
49
|
+
npx --yes @palettelab/cli@latest dev --sandbox --env staging
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The hosted sandbox flow packages the app, uploads it to the configured Palette
|
|
53
|
+
environment, creates a preview publish, and prints a real OS preview URL. Use
|
|
54
|
+
that URL to test routing, OS shell behavior, login context, organization
|
|
55
|
+
context, Data Room APIs, storage, install/review behavior, logs, permissions,
|
|
56
|
+
and platform APIs.
|
|
57
|
+
|
|
58
|
+
## Staging URL
|
|
59
|
+
|
|
60
|
+
The staging URL is the base URL of the Palette platform backend/API
|
|
61
|
+
environment. The CLI appends the API paths itself, for example:
|
|
62
|
+
|
|
63
|
+
- `/api/v1/appstore/sign-upload`
|
|
64
|
+
- `/api/v1/appstore/publish`
|
|
65
|
+
- `/api/v1/developer/publish-tokens`
|
|
66
|
+
- `/api/superadmin/publish-tokens`
|
|
67
|
+
|
|
68
|
+
Use the same public origin only if that origin proxies API routes to the
|
|
69
|
+
backend. For example, `https://apps.pltt.xyz` is valid only when these paths are
|
|
70
|
+
served by the backend, not by the frontend catch-all route:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
/api/v1/*
|
|
74
|
+
/api/superadmin/*
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Validate a staging URL before giving it to developers:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
curl https://YOUR-PALETTE-STAGING-URL/api/v1/health
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A valid staging URL returns a backend health JSON response. If it returns the
|
|
84
|
+
Palette frontend HTML, it is a frontend-only URL and the CLI cannot publish to
|
|
85
|
+
it. In that case either use the real backend domain, for example
|
|
86
|
+
`https://api.your-domain.example`, or update the web server/reverse proxy so
|
|
87
|
+
`/api/v1/*` and `/api/superadmin/*` go to the backend.
|
|
88
|
+
|
|
89
|
+
## Publish Token
|
|
90
|
+
|
|
91
|
+
Every developer needs a publish token before they can use hosted sandbox or
|
|
92
|
+
publish commands. Tokens start with `pltt_`.
|
|
93
|
+
|
|
94
|
+
Developers can create their own token after logging in to Palette:
|
|
95
|
+
|
|
96
|
+
1. Open Palette OS in the browser.
|
|
97
|
+
2. Open Settings.
|
|
98
|
+
3. Go to Developer.
|
|
99
|
+
4. Create a developer publish token.
|
|
100
|
+
5. Copy the token immediately. The raw token is shown only once.
|
|
101
|
+
|
|
102
|
+
Superadmins can also allocate tokens from the superadmin publish-token section.
|
|
103
|
+
Use superadmin allocation for service accounts, CI, or developers who should
|
|
104
|
+
not create their own token.
|
|
105
|
+
|
|
106
|
+
Do not commit tokens to a repository. Store them through `pltt login` or an
|
|
107
|
+
environment variable.
|
|
108
|
+
|
|
109
|
+
## Configure A Hosted Sandbox
|
|
110
|
+
|
|
111
|
+
The recommended setup is `pltt login`, which writes
|
|
112
|
+
`~/.palette/config.json` with file mode `0600`:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npx --yes @palettelab/cli@latest login \
|
|
116
|
+
--env staging \
|
|
117
|
+
--url https://YOUR-PALETTE-STAGING-URL \
|
|
118
|
+
--token pltt_xxxxx
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
You can verify the saved environment with:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
cat ~/.palette/config.json
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
You can also use environment variables instead of storing the token:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
export PALETTE_STAGING_URL=https://YOUR-PALETTE-STAGING-URL
|
|
131
|
+
export PALETTE_STAGING_TOKEN=pltt_xxxxx
|
|
132
|
+
npx --yes @palettelab/cli@latest dev --sandbox --env staging
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Environment variable precedence:
|
|
136
|
+
|
|
137
|
+
1. `PALETTE_<ENV>_URL` and `PALETTE_<ENV>_TOKEN`
|
|
138
|
+
2. `PALETTE_PUBLISH_TOKEN` as a token fallback
|
|
139
|
+
3. `~/.palette/config.json`
|
|
140
|
+
4. `./palette.config.json` for repo-local overrides
|
|
141
|
+
|
|
142
|
+
## Test Inside The Real Palette OS Without Docker
|
|
143
|
+
|
|
144
|
+
Use hosted sandbox for real OS testing:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npx --yes @palettelab/cli@latest dev --sandbox --env staging
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
This is the correct flow for internal teams that need real platform features
|
|
151
|
+
without pushing the app to production approval and without running Docker on the
|
|
152
|
+
developer machine.
|
|
153
|
+
|
|
154
|
+
Expected behavior:
|
|
155
|
+
|
|
156
|
+
1. The CLI runs local contract checks.
|
|
157
|
+
2. The CLI bundles frontend and backend artifacts.
|
|
158
|
+
3. The CLI uploads the package to the staging Palette environment.
|
|
159
|
+
4. The platform creates a preview/review publish.
|
|
160
|
+
5. The CLI prints the preview URL, status command, and logs command.
|
|
161
|
+
6. The developer opens the preview URL inside the real Palette OS.
|
|
162
|
+
|
|
163
|
+
For developer sandboxes where manual review should not block testing, the
|
|
164
|
+
backend environment should run with:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
With that backend setting enabled, passing sandbox preview publishes are marked
|
|
171
|
+
active automatically, so developers can test OS shell, auth, Data Room,
|
|
172
|
+
organization, install, permission, log, and platform API behavior immediately.
|
|
173
|
+
|
|
174
|
+
Useful follow-up commands:
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
npx --yes @palettelab/cli@latest status --env staging
|
|
178
|
+
npx --yes @palettelab/cli@latest logs simple-todo --env staging --follow
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Local-Only Versus OS Testing
|
|
182
|
+
|
|
183
|
+
Use the right command for the kind of test you need:
|
|
184
|
+
|
|
185
|
+
| Goal | Command | Docker | Uses real OS services |
|
|
186
|
+
|---|---|---:|---:|
|
|
187
|
+
| Fast SDK/frontend/backend loop | `pltt dev` | No | No |
|
|
188
|
+
| Real OS preview in hosted cloud sandbox | `pltt dev --sandbox --env staging` | No | Yes |
|
|
189
|
+
| Alias for hosted cloud sandbox | `pltt dev --cloud --env staging` | No | Yes |
|
|
190
|
+
| Internal full local platform parity | `pltt dev --platform` | Yes | Local platform container |
|
|
191
|
+
| Production/review publish | `pltt publish --env production` | No | Yes |
|
|
192
|
+
|
|
193
|
+
For normal app developers, Docker is not required. Docker is only needed for
|
|
194
|
+
internal platform parity checks with `pltt dev --platform`.
|
|
195
|
+
|
|
24
196
|
## Commands
|
|
25
197
|
|
|
26
198
|
### `pltt init <name>`
|