revisium 2.5.0-alpha.2 → 2.5.0-alpha.3

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.
Files changed (8) hide show
  1. package/README.md +49 -154
  2. package/dist/package.json +1 -1
  3. package/dist/tsconfig.build.tsbuildinfo +1 -1
  4. package/docs/bootstrap-commands.md +37 -3
  5. package/docs/concepts.md +63 -0
  6. package/docs/quickstart.md +115 -0
  7. package/docs/workflows.md +100 -0
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -8,201 +8,94 @@
8
8
  [![GitHub License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/revisium/revisium-cli/blob/master/LICENSE)
9
9
  [![GitHub Release](https://img.shields.io/github/v/release/revisium/revisium-cli)](https://github.com/revisium/revisium-cli/releases)
10
10
 
11
- **Command-line interface for managing Revisium projects**
11
+ **Command-line interface for Revisium** — manage migrations, seed data, and move projects between instances.
12
12
 
13
13
  </div>
14
14
 
15
- ## Overview
15
+ ## What is Revisium?
16
16
 
17
- A CLI tool for interacting with Revisium instances, providing migration management, schema export, data export, and project synchronization capabilities.
17
+ A versioned headless CMS / data platform with Git-like branches and revisions. See [revisium.io](https://revisium.io) and [docs.revisium.io](https://docs.revisium.io) for the product reference.
18
18
 
19
- ## Features
19
+ This CLI wraps the Revisium HTTP API for everyday CI/CD and developer flows.
20
20
 
21
- - **Migration Management** - Save and apply database migrations with auto-commit
22
- - **Schema Export/Import** - Export table schemas and convert to migrations
23
- - **Data Export/Upload** - Export and upload rows with smart dependency handling
24
- - **Project Sync** - Synchronize schema and data between Revisium projects
25
- - **Bulk Operations** - Efficient batch operations with configurable batch size
26
- - **Docker Deployment** - Containerized automation for CI/CD
27
-
28
- ## Installation
21
+ ## Install
29
22
 
30
23
  ```bash
31
- # Install globally
32
- npm install -g revisium
33
-
34
- # Or use with npx
35
- npx revisium --help
36
- ```
37
-
38
- ## Examples
39
-
40
- ### CI/CD Migrations (Prisma-like Workflow)
41
-
42
- ```
43
- ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
44
- │ DEV │ │ GIT │ │ CI/CD │
45
- │ │ │ │ │ │
46
- │ Revisium │ save │ migrations │ push │ apply │
47
- │ UI │─────▶│ .json │─────▶│ migrations │
48
- │ │ │ data/ │ │ + seed │
49
- └─────────────┘ └─────────────┘ └─────────────┘
24
+ npm install -g revisium # global
25
+ npx revisium --help # ad-hoc
50
26
  ```
51
27
 
52
- Like Prisma, save schema migrations locally and apply them in CI/CD:
28
+ ## Quickstart (60 seconds, local)
53
29
 
54
30
  ```bash
55
- # 1. Save migrations locally (during development)
56
- revisium migrate save --file ./revisium/migrations.json \
57
- --url revisium://admin:admin@localhost:8080/myorg/myproject/master
58
-
59
- # 2. Commit to git
60
- git add revisium/migrations.json
61
- git commit -m "Add new schema fields"
62
-
63
- # 3. Apply in CI/CD (on deploy)
64
- revisium migrate apply --file ./revisium/migrations.json --commit \
65
- --url revisium://cloud.revisium.io/myorg/myproject/master
66
- ```
67
-
68
- Add to package.json scripts:
69
-
70
- ```json
71
- {
72
- "scripts": {
73
- "revisium:save-migrations": "revisium migrate save --file ./revisium/migrations.json",
74
- "revisium:apply-migrations": "revisium migrate apply --file ./revisium/migrations.json --commit",
75
- "start:prod": "npm run revisium:apply-migrations && node dist/main"
76
- }
77
- }
78
- ```
79
-
80
- See [Docker Deployment](docs/docker-deployment.md) for complete CI/CD examples.
81
-
82
- ### Export & Import (File-based)
83
-
84
- ```
85
- ┌─────────────┐ ┌─────────────┐
86
- │ SOURCE │ migrations.json │ TARGET │
87
- │ Revisium │ ────────────────────▶ │ Revisium │
88
- │ │ data/ │ │
89
- └─────────────┘ └─────────────┘
90
- ```
31
+ # 1. Boot a local Revisium with embedded PostgreSQL in another terminal.
32
+ # No --auth flag = no credentials needed for the rest of this quickstart.
33
+ npx -y @revisium/standalone
91
34
 
92
- Save project to files for backup or deployment to another instance:
35
+ # 2. Grab the example bootstrap config (or write your own — see docs/quickstart.md).
36
+ curl -O https://raw.githubusercontent.com/revisium/revisium-cli/master/examples/quickstart/bootstrap.config.json
93
37
 
94
- ```bash
95
- # Export from source
96
- revisium migrate save --file ./migrations.json
97
- revisium rows save --folder ./data
98
-
99
- # Import to target
100
- revisium migrate apply --file ./migrations.json --commit \
101
- --url revisium://target.example.com/org/proj/main
102
- revisium rows upload --folder ./data --commit \
103
- --url revisium://target.example.com/org/proj/master
104
- ```
105
-
106
- ### Sync (Direct Transfer)
38
+ # 3. Bootstrap a project + table + row + REST endpoint.
39
+ revisium example bootstrap \
40
+ --config ./bootstrap.config.json \
41
+ --url revisium://localhost:9222/admin/hello/master \
42
+ --commit
107
43
 
108
- ```
109
- ┌─────────────┐ ┌─────────────┐
110
- │ SOURCE │ schema + data │ TARGET │
111
- │ Revisium │ ════════════════════▶ │ Revisium │
112
- │ │ (direct) │ :draft │
113
- └─────────────┘ └─────────────┘
44
+ # 4. Hit your fresh REST endpoint.
45
+ curl http://localhost:9222/endpoint/rest/admin/hello/master/draft/Note/first
114
46
  ```
115
47
 
116
- Synchronize directly between two projects without intermediate files:
48
+ Full walkthrough: [docs/quickstart.md](docs/quickstart.md). For a Revisium that requires login, see [docs/authentication.md](docs/authentication.md).
117
49
 
118
- ```bash
119
- # With tokens in URL
120
- revisium sync all \
121
- --source revisium://source.example.com/org/proj/master:head?token=xxx \
122
- --target revisium://target.example.com/org/proj/master?token=yyy \
123
- --commit
50
+ ## Use cases
124
51
 
125
- # With tokens via environment (recommended for CI/CD)
126
- export REVISIUM_SOURCE_TOKEN=$SOURCE_TOKEN
127
- export REVISIUM_TARGET_TOKEN=$TARGET_TOKEN
128
- revisium sync all \
129
- --source revisium://source.example.com/org/proj/master:head \
130
- --target revisium://target.example.com/org/proj/master \
131
- --commit
132
- ```
52
+ - **Manage migrations and seeding in CI/CD** — `migrate save/apply` plus `rows upload` for seed data, driven from a JSON file in git. Walk: [docs.revisium.io/migrations/ci-cd](https://docs.revisium.io/migrations/ci-cd).
53
+ - **Sync between live instances** — `sync schema/data/all` copies a project directly between two Revisium instances without intermediate files. Walk: [docs/workflows.md#2-sync-between-two-live-instances](docs/workflows.md#2-sync-between-two-live-instances).
54
+ - **Download / upload (data portability)** — `schema save` / `rows save` / `migrate save` export to JSON; `migrate apply` / `rows upload` import. Useful for backups, fixtures, and air-gapped transfers. Walk: [docs/workflows.md#3-download--upload-data-portability](docs/workflows.md#3-download--upload-data-portability).
133
55
 
134
56
  ## Commands
135
57
 
136
58
  | Command | Description | Documentation |
137
59
  | ------------------------------------- | -------------------------------------- | ------------------------------------------------ |
138
- | `schema save` | Export table schemas to JSON files | [Schema Commands](docs/schema-commands.md) |
139
- | `schema create-migrations` | Convert schemas to migration format | [Schema Commands](docs/schema-commands.md) |
140
60
  | `migrate save` | Export migrations to JSON file | [Migrate Commands](docs/migrate-commands.md) |
141
61
  | `migrate apply` | Apply migrations from JSON file | [Migrate Commands](docs/migrate-commands.md) |
62
+ | `schema save` | Export table schemas to JSON files | [Schema Commands](docs/schema-commands.md) |
63
+ | `schema create-migrations` | Convert schemas to migration format | [Schema Commands](docs/schema-commands.md) |
142
64
  | `rows save` | Export table data to JSON files | [Rows Commands](docs/rows-commands.md) |
143
65
  | `rows upload` | Upload table data from JSON files | [Rows Commands](docs/rows-commands.md) |
144
66
  | `sync schema` | Sync schema between projects | [Sync Commands](docs/sync-commands.md) |
145
67
  | `sync data` | Sync data between projects | [Sync Commands](docs/sync-commands.md) |
146
68
  | `sync all` | Full sync (schema + data) | [Sync Commands](docs/sync-commands.md) |
147
- | `instance add/list/show/remove` | Manage workspace Revisium instances | [Workspace Config](docs/workspace-config.md) |
148
- | `context create/list/show/use/remove` | Manage workspace Revisium contexts | [Workspace Config](docs/workspace-config.md) |
149
- | `auth login/status/logout` | Manage saved API-key credentials | [Authentication](docs/authentication.md) |
150
69
  | `project ensure` | Ensure a project and branch exist | [Bootstrap Commands](docs/bootstrap-commands.md) |
151
70
  | `endpoint ensure/list` | Ensure or list generated endpoints | [Bootstrap Commands](docs/bootstrap-commands.md) |
152
- | `example bootstrap` | Bootstrap example projects from config | [Bootstrap Commands](docs/bootstrap-commands.md) |
71
+ | `example bootstrap` | Bootstrap a project from config | [Bootstrap Commands](docs/bootstrap-commands.md) |
72
+ | `auth login/status/logout` | Manage saved API-key credentials | [Authentication](docs/authentication.md) |
73
+ | `instance add/list/show/remove` | Manage workspace Revisium instances | [Workspace Config](docs/workspace-config.md) |
74
+ | `context create/list/show/use/remove` | Manage workspace Revisium contexts | [Workspace Config](docs/workspace-config.md) |
153
75
 
154
76
  ## Configuration
155
77
 
156
- Configure via workspace config, environment variables, or `.env` file:
157
-
158
- ```bash
159
- # Workspace-local standalone example without auth
160
- revisium instance add local --url revisium://localhost:9222 --auth none
161
- revisium context create dictionary-local \
162
- --url revisium://localhost:9222/admin/dictionary/master
163
- revisium context use dictionary-local
164
- ```
165
-
166
- Then single-target commands can omit `--url` in that workspace.
167
-
168
- ```env
169
- # Recommended: URL + Token
170
- REVISIUM_URL=revisium://cloud.revisium.io/your_org/your_project/main
171
- REVISIUM_TOKEN=your_jwt_token
78
+ Pick the auth method that matches the context:
172
79
 
173
- # Alternative: URL + Username/Password
174
- REVISIUM_URL=revisium://cloud.revisium.io/your_org/your_project/main
175
- REVISIUM_USERNAME=your_username
176
- REVISIUM_PASSWORD=your_password
177
- ```
80
+ - **Saved API key** — recommended for local dev. Run `revisium auth login` once; the key lives in the OS keyring and is reused automatically.
81
+ - **Environment variables** — recommended for CI. `REVISIUM_TOKEN` (or `REVISIUM_API_KEY`) plus `REVISIUM_URL`.
82
+ - **Workspace contexts** — for multi-target setups. `revisium instance add` and `revisium context create` save non-secret config under `.revisium/revisium-cli.config.json`.
178
83
 
179
- Or use command-line `--url` option with credentials via environment:
84
+ Full precedence rules and every supported method: [docs/authentication.md](docs/authentication.md), [docs/configuration.md](docs/configuration.md).
180
85
 
181
- ```bash
182
- # Token in environment, target in URL
183
- export REVISIUM_TOKEN=$MY_TOKEN
184
- revisium schema save --folder ./schemas \
185
- --url revisium://cloud.revisium.io/my-org/my-project/develop
186
-
187
- # Token in URL query parameter
188
- revisium schema save --folder ./schemas \
189
- --url revisium://cloud.revisium.io/my-org/my-project/develop?token=$TOKEN
190
- ```
86
+ ## Documentation
191
87
 
192
- See [Configuration](docs/configuration.md) and [URL Format](docs/url-format.md) for details.
88
+ - [Quickstart](docs/quickstart.md) — run the CLI against a local Revisium in five minutes.
89
+ - [Concepts](docs/concepts.md) — primitives the CLI works with.
90
+ - [Common workflows](docs/workflows.md) — named recipes (CI/CD, sync, portability).
91
+ - [Authentication](docs/authentication.md) · [Configuration](docs/configuration.md) · [URL Format](docs/url-format.md) · [Workspace Config](docs/workspace-config.md)
92
+ - Per-command: [migrate](docs/migrate-commands.md) · [schema](docs/schema-commands.md) · [rows](docs/rows-commands.md) · [sync](docs/sync-commands.md) · [bootstrap](docs/bootstrap-commands.md)
93
+ - [Docker deployment](docs/docker-deployment.md)
94
+ - Product docs: [docs.revisium.io](https://docs.revisium.io)
193
95
 
194
- ## Documentation
96
+ ## Compatibility
195
97
 
196
- - [Configuration](docs/configuration.md) - Environment variables and .env files
197
- - [Workspace Config](docs/workspace-config.md) - non-secret instances and contexts
198
- - [Bootstrap Commands](docs/bootstrap-commands.md) - project, endpoint, and example bootstrap workflows
199
- - [URL Format](docs/url-format.md) - Revisium URL syntax
200
- - [Authentication](docs/authentication.md) - Token, API key, and password auth
201
- - [Schema Commands](docs/schema-commands.md) - schema save, create-migrations
202
- - [Migrate Commands](docs/migrate-commands.md) - migrate save, apply
203
- - [Rows Commands](docs/rows-commands.md) - rows save, upload
204
- - [Sync Commands](docs/sync-commands.md) - sync schema, data, all
205
- - [Docker Deployment](docs/docker-deployment.md) - Docker, Kubernetes, CI/CD
98
+ The current CLI targets `@revisium/standalone` 2.8.x and current `cloud.revisium.io`.
206
99
 
207
100
  ## Development
208
101
 
@@ -213,6 +106,8 @@ npm install
213
106
  npm run build
214
107
  ```
215
108
 
109
+ Conventions and the verify checklist for contributors are in [AGENTS.md](AGENTS.md).
110
+
216
111
  ## License
217
112
 
218
- MIT License - see [LICENSE](LICENSE) file for details.
113
+ MIT — see [LICENSE](LICENSE).
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "revisium",
3
- "version": "2.5.0-alpha.2",
3
+ "version": "2.5.0-alpha.3",
4
4
  "homepage": "https://revisium.io",
5
5
  "description": "A CLI tool for interacting with Revisium instances, providing migration management, schema export, and data export capabilities.",
6
6
  "author": "Anton Kashirov",