Skip to content

Commit 4f0afa1

Browse files
hotlonghotlong
committed
docs: update CLI documentation with latest commands: init, new, serve, i18n, migrate
1 parent 6ce940d commit 4f0afa1

1 file changed

Lines changed: 185 additions & 29 deletions

File tree

‎docs/guide/cli.md‎

Lines changed: 185 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,36 @@ npm install -D @objectql/cli
1212

1313
You can then run it via `npx objectql` or add scripts to your `package.json`.
1414

15-
## 2. Commands
15+
## 2. Core Commands
1616

17-
### 2.1 `generate` (Type Generation)
17+
### 2.1 `init` (Create Project)
1818

19-
Scans your `*.object.yml` files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions.
19+
Create a new ObjectQL project from a starter template.
20+
21+
```bash
22+
npx objectql init [options]
23+
```
24+
25+
**Options:**
26+
27+
| Option | Alias | Default | Description |
28+
| :--- | :--- | :--- | :--- |
29+
| `--template <template>` | `-t` | `basic` | Template to use (`basic`, `express-api`, `enterprise`). |
30+
| `--name <name>` | `-n` | - | Project name. |
31+
| `--dir <path>` | `-d` | - | Target directory. |
32+
| `--skip-install` | | `false` | Skip dependency installation. |
33+
| `--skip-git` | | `false` | Skip git initialization. |
34+
35+
**Example:**
36+
37+
```bash
38+
npx objectql init -t express-api -n my-app
39+
```
2040

21-
**Usage:**
41+
### 2.2 `generate` (Type Generation)
42+
43+
Scans your `*.object.yml` files and generates TypeScript interfaces. This is crucial for maintaining type safety in your Hooks and Actions.
44+
**Alias**: `g`
2245

2346
```bash
2447
npx objectql generate [options]
@@ -28,8 +51,8 @@ npx objectql generate [options]
2851

2952
| Option | Alias | Default | Description |
3053
| :--- | :--- | :--- | :--- |
31-
| `--source` | `-s` | `.` | Root directory to search for object files. |
32-
| `--output` | `-o` | `./src/generated` | Directory where `.ts` files will be generated. |
54+
| `--source <path>` | `-s` | `.` | Root directory to search for object files. |
55+
| `--output <path>` | `-o` | `./src/generated` | Directory where `.ts` files will be generated. |
3356

3457
**Example:**
3558

@@ -38,54 +61,186 @@ npx objectql generate [options]
3861
npx objectql generate --source ./src/objects --output ./src/types
3962
```
4063

41-
### 2.2 `repl` (Interactive Shell)
64+
### 2.3 `new` (Scaffold Metadata)
4265

43-
Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
66+
Generate a new metadata file (Object, View, Form, etc.) in the project.
67+
68+
```bash
69+
npx objectql new <type> <name> [options]
70+
```
71+
72+
**Arguments:**
73+
* `<type>`: The type of metadata to generate (e.g., `object`, `view`, `page`).
74+
* `<name>`: The name of the file/entity.
75+
76+
**Options:**
77+
78+
| Option | Alias | Default | Description |
79+
| :--- | :--- | :--- | :--- |
80+
| `--dir <path>` | `-d` | `.` | Output directory. |
81+
82+
**Example:**
83+
```bash
84+
npx objectql new object customer
85+
```
86+
87+
## 3. Development Tools
88+
89+
### 3.1 `serve` (Dev Server)
90+
91+
Start a standalone development server.
92+
**Alias**: `s`
93+
94+
```bash
95+
npx objectql serve [options]
96+
```
97+
98+
**Options:**
99+
100+
| Option | Alias | Default | Description |
101+
| :--- | :--- | :--- | :--- |
102+
| `--port <number>` | `-p` | `3000` | Port to listen on. |
103+
| `--dir <path>` | `-d` | `.` | Directory containing schema. |
104+
105+
### 3.2 `studio` (Admin UI)
44106

45-
**Prerequisites:**
107+
Starts the web-based admin studio to browse data and view schema.
108+
**Alias**: `ui`
109+
110+
```bash
111+
npx objectql studio [options]
112+
```
113+
114+
**Options:**
115+
116+
| Option | Alias | Default | Description |
117+
| :--- | :--- | :--- | :--- |
118+
| `--port <number>` | `-p` | `3000` | Port to listen on. |
119+
| `--dir <path>` | `-d` | `.` | Directory containing schema. |
120+
| `--no-open` | | `false` | Do not open the browser automatically. |
46121

47-
You must have an `objectql.config.ts` or `objectql.config.js` file in your project root that exports your configured `ObjectQL` instance (default export or named export `app`).
122+
### 3.3 `repl` (Interactive Shell)
48123

49-
**Usage:**
124+
Starts an interactive terminal similar to the MongoDB shell, allowing you to directly query your database using the ObjectQL API.
125+
**Alias**: `r`
50126

51127
```bash
52-
npx objectql repl
128+
npx objectql repl [options]
53129
```
54130

55-
**Features:**
56-
* **Auto-injected Objects:** All your registered objects are available as global variables (e.g., `await tasks.find()`).
57-
* **Context:** The `app` instance is available as `app`.
58-
* **Sudo Access:** Commands run with system privileges by default in the REPL.
131+
**Options:**
132+
133+
| Option | Alias | Default | Description |
134+
| :--- | :--- | :--- | :--- |
135+
| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
59136

60137
**Example Session:**
61138

62139
```javascript
63140
objectql> await tasks.find({ status: 'todo' })
64141
[ { id: 1, title: 'Fix bug', status: 'todo' } ]
142+
```
143+
144+
## 4. Internationalization (i18n)
145+
146+
Tools for managing translations.
147+
148+
### 4.1 `i18n extract`
65149

66-
objectql> await projects.create({ name: 'New API' })
67-
{ id: 10, name: 'New API', ... }
150+
Extract translatable strings from metadata files into JSON.
151+
152+
```bash
153+
npx objectql i18n extract [options]
68154
```
69155

70-
### 2.3 `studio` (Admin UI)
156+
**Options:**
157+
158+
| Option | Alias | Default | Description |
159+
| :--- | :--- | :--- | :--- |
160+
| `--source <path>` | `-s` | `.` | Source directory to scan. |
161+
| `--output <path>` | `-o` | `./src/i18n` | Output directory for translation files. |
162+
| `--lang <lang>` | `-l` | `en` | Language code. |
71163

72-
Starts the web-based admin studio to browse data and view schema.
73-
Requires `objectql.config.ts` (or `.js`) to be present in the directory.
164+
### 4.2 `i18n init`
165+
166+
Initialize i18n structure for a new language.
167+
168+
```bash
169+
npx objectql i18n init <lang> [options]
170+
```
171+
172+
**Options:**
173+
174+
| Option | Alias | Default | Description |
175+
| :--- | :--- | :--- | :--- |
176+
| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
177+
178+
### 4.3 `i18n validate`
179+
180+
Validate translation completeness against a base language.
181+
182+
```bash
183+
npx objectql i18n validate <lang> [options]
184+
```
185+
186+
**Options:**
187+
188+
| Option | Alias | Default | Description |
189+
| :--- | :--- | :--- | :--- |
190+
| `--base-dir <path>` | `-b` | `./src/i18n` | Base i18n directory. |
191+
| `--base-lang <lang>` | | `en` | Base language to compare against. |
192+
193+
## 5. Database Migration
194+
195+
Manage database schema changes.
196+
197+
### 5.1 `migrate`
198+
199+
Run pending database migrations.
200+
201+
```bash
202+
npx objectql migrate [options]
203+
```
204+
205+
**Options:**
206+
207+
| Option | Alias | Default | Description |
208+
| :--- | :--- | :--- | :--- |
209+
| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
210+
| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
211+
212+
### 5.2 `migrate create`
213+
214+
Create a new migration file.
74215

75216
```bash
76-
npx objectql studio
217+
npx objectql migrate create <name> [options]
77218
```
78219

79-
### 2.4 `migration` (Coming Soon)
220+
**Options:**
221+
222+
| Option | Alias | Default | Description |
223+
| :--- | :--- | :--- | :--- |
224+
| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
225+
226+
### 5.3 `migrate status`
80227

81-
Future versions will include migration commands to sync your YAML schema with the database.
228+
Show the status of migrations (applied/pending).
82229

83-
* `migration:create`: Create a new SQL migration file based on schema changes.
84-
* `migration:run`: Apply pending migrations to the database.
230+
```bash
231+
npx objectql migrate status [options]
232+
```
233+
234+
**Options:**
235+
236+
| Option | Alias | Default | Description |
237+
| :--- | :--- | :--- | :--- |
238+
| `--config <path>` | `-c` | - | Path to `objectql.config.ts/js`. |
239+
| `--dir <path>` | `-d` | `./migrations` | Migrations directory. |
85240

86-
## 3. Integration with Workflow
241+
## 6. Integration with Workflow
87242

88-
We recommend adding the generation command to your lifecycle scripts.
243+
We recommend adding the CLI commands to your lifecycle scripts.
89244

90245
**package.json:**
91246

@@ -94,7 +249,8 @@ We recommend adding the generation command to your lifecycle scripts.
94249
"scripts": {
95250
"codegen": "objectql generate -s ./src -o ./src/generated",
96251
"build": "npm run codegen && tsc",
97-
"dev": "npm run codegen && ts-node src/index.ts"
252+
"dev": "npm run codegen && ts-node src/index.ts",
253+
"studio": "objectql studio"
98254
}
99255
}
100256
```

0 commit comments

Comments
 (0)