create-apiagex

English

create-apiagex is the installer CLI for starting a new Apiagex project.

Current CLI behavior:

• Prints help with create-apiagex --help.
• Prints version with create-apiagex --version.
• Prompts for project name and setup choices in an interactive terminal.
• Supports --yes and setup flags for CI/non-interactive scaffolding.
• Validates that the target folder is a safe slug like my-cms.
• Refuses to overwrite an existing non-empty folder.
• Supports --dry-run to show the scaffold plan without writing files.
• Creates a small starter scaffold when the target folder is missing or empty.

Interactive setup asks for setup mode, database provider, SQLite database path or PostgreSQL/MySQL database URL, host, port, package manager, dependency install preference, git init preference, and optional first owner bootstrap credentials. TypeScript is the default language. Use --language js when a JavaScript starter is preferred.

Generated starter files:

• package.json
• .gitignore
• .env
• .env.example
• apiagex.config.json
• src/index.ts by default, or src/index.js with --language js
• src/custom-routes.ts by default, or src/custom-routes.js with --language js
• tsconfig.json for TypeScript projects
• README.md
• docs/README.md

The generated .env stores local setup values such as APIAGEX_DATABASE_PROVIDER, APIAGEX_DATABASE_PATH for SQLite or APIAGEX_DATABASE_URL for PostgreSQL/MySQL, APIAGEX_UPLOADS_PATH, APIAGEX_SECRET, HOST, and PORT. If owner bootstrap is enabled, .env also contains APIAGEX_OWNER_EMAIL and APIAGEX_OWNER_PASSWORD; remove the password after the first successful start.

The generated package.json depends on @apiagex/server and exposes npm run dev, npm run start, npm run smoke, and npm run build. TypeScript projects also expose npm run types.

The generated src/custom-routes.ts or src/custom-routes.js is the place for business APIs such as checkout, pay order, assign rider, and reports. Write routes such as /orders/:id/pay; Apiagex mounts them under /api/custom/orders/:id/pay, discovers them for Admin UI, and blocks them until Settings / Custom API Permissions allows a role.

Practical custom route flow:

1. Add a route in src/custom-routes.ts, for example app.post("/orders/:entryId/pay", handler).
2. Restart the server. It appears as POST /api/custom/orders/:entryId/pay.
3. Open /adminui#settings/custom-api-permissions, select the content API role, search the route, allow it, and save.
4. Open Settings / API Tokens, create a token for that role, then call it:

curl -X POST http://127.0.0.1:4000/api/custom/orders/ENTRY_ID/pay \
  -H "Authorization: Bearer API_TOKEN"

The same screen can rename the route label/group, show allow/block history, and delete old inactive routes after they are removed from code.

Workflow APIs created in Admin UI use the same Custom API Permissions system. Create an active workflow in /adminui#settings/workflows; it is mounted under /api/custom. Then allow its route for public or for a content API role in /adminui#settings/custom-api-permissions.

Public workflow call:

curl -X POST http://127.0.0.1:4000/api/custom/orders/status \
  -H "content-type: application/json" \
  -d '{"orderId":"ord_123","status":"ready"}'

Token-protected workflow call:

curl -X POST http://127.0.0.1:4000/api/custom/orders/status \
  -H "Authorization: Bearer API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"orderId":"ord_123","status":"ready"}'

Blocked workflow calls return CUSTOM_API_PERMISSION_DENIED. Wrong or revoked tokens return API_TOKEN_INVALID. Inactive workflows are not mounted.

Register template: Settings / Workflows can create an inactive POST /api/custom/auth/register starter. Create a users content schema with email, passwordHash, and status fields first. The template validates password but does not store it; replace PASSWORD_HASH_PLACEHOLDER_REPLACE_WITH_SERVER_SIDE_HASHING with real server-side hashing before production.

For TypeScript projects, run this after creating or changing schemas in Admin UI:

npm run types

It generates src/apiagex-types.ts so RegisterApiagexCustomRoutes automatically gets schema slug and field autocomplete. Custom routes can call typed helpers such as apiagex.schemas.getBySlug("products"), apiagex.entries.query("products", options), and apiagex.entries.create("products", { data }).

The generated starter README points users to /doc, /readme, and /adminui, includes practical owner/schema/entry/role/webhook/realtime flow, and explains common errors.

The generated docs/README.md explains generated API shape, custom business APIs, access control, webhooks, realtime, relation docs, payloads, populate options, Admin UI entry pickers, and common errors.

The generated-project test verifies this scaffold without network installs by creating a temporary project, running the runtime smoke command, starting Apiagex on a temporary port/database, and checking /api/health, /adminui, /doc, and /readme.

Example:

npm create apiagex@latest my-cms
npx create-apiagex my-cms
npx create-apiagex my-cms --language js
npm run build -w create-apiagex
node packages/create-apiagex/dist/index.js my-cms --dry-run
node packages/create-apiagex/dist/index.js my-cms --yes
node packages/create-apiagex/dist/index.js --dry-run

Local workspace test before publishing:

npm run build -w create-apiagex
cd newproject
npx create-apiagex my-cms --yes

After scaffolding:

cd my-cms
npm install
npm run dev

Hinglish

create-apiagex new Apiagex project start karne ke liye installer CLI hai.

Current CLI behavior:

• create-apiagex --help se help print hoti hai.
• create-apiagex --version se version print hota hai.
• Interactive terminal me project name aur setup choices puche jaate hain.
• CI/non-interactive scaffold ke liye --yes aur setup flags support hain.
• Target folder safe slug hona chahiye, jaise my-cms.
• Existing non-empty folder overwrite nahi hota.
• --dry-run scaffold plan dikhata hai bina files likhe.
• Target folder missing ya empty ho to small starter scaffold create hota hai.

Interactive setup setup mode, database provider, SQLite database path ya PostgreSQL/MySQL database URL, host, port, package manager, dependency install preference, git init preference, aur optional first owner bootstrap credentials puchta hai. TypeScript default language hai. JavaScript starter chahiye ho to --language js use karo.

Generated starter files:

• package.json
• .gitignore
• .env
• .env.example
• apiagex.config.json
• default me src/index.ts, ya --language js ke saath src/index.js
• default me src/custom-routes.ts, ya --language js ke saath src/custom-routes.js
• TypeScript projects ke liye tsconfig.json
• README.md
• docs/README.md

Generated .env local setup values store karta hai, jaise APIAGEX_DATABASE_PROVIDER, SQLite ke liye APIAGEX_DATABASE_PATH ya PostgreSQL/MySQL ke liye APIAGEX_DATABASE_URL, APIAGEX_UPLOADS_PATH, APIAGEX_SECRET, HOST, aur PORT. Owner bootstrap enable ho to .env me APIAGEX_OWNER_EMAIL aur APIAGEX_OWNER_PASSWORD bhi hota hai; first successful start ke baad password hata do.

Generated package.json @apiagex/server par depend karta hai aur npm run dev, npm run start, npm run smoke, aur npm run build expose karta hai. TypeScript projects me npm run types bhi hota hai.

Generated src/custom-routes.ts ya src/custom-routes.js business APIs ke liye jagah hai, jaise checkout, pay order, assign rider, aur reports. Route /orders/:id/pay jaisa likho; Apiagex usko /api/custom/orders/:id/pay par mount karta hai, Admin UI me discover karta hai, aur Settings / Custom API Permissions me role allow hone tak block rakhta hai.

Practical custom route flow:

1. src/custom-routes.ts me route add karo, jaise app.post("/orders/:entryId/pay", handler).
2. Server restart karo. Ye POST /api/custom/orders/:entryId/pay ke roop me dikhega.
3. /adminui#settings/custom-api-permissions open karo, content API role select karo, route search karo, allow karo, aur save karo.
4. Settings / API Tokens me us role ka token banao, phir call karo:

curl -X POST http://127.0.0.1:4000/api/custom/orders/ENTRY_ID/pay \
  -H "Authorization: Bearer API_TOKEN"

Same screen se route label/group rename, allow/block history, aur code se remove hone ke baad old inactive route delete bhi ho sakta hai.

Admin UI me bani Workflow APIs same Custom API Permissions system use karti hain. /adminui#settings/workflows me active workflow banao; ye /api/custom ke under mount hota hai. Phir /adminui#settings/custom-api-permissions me us route ko public ya content API role ke liye allow karo.

Public workflow call:

curl -X POST http://127.0.0.1:4000/api/custom/orders/status \
  -H "content-type: application/json" \
  -d '{"orderId":"ord_123","status":"ready"}'

Token-protected workflow call:

curl -X POST http://127.0.0.1:4000/api/custom/orders/status \
  -H "Authorization: Bearer API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"orderId":"ord_123","status":"ready"}'

Blocked workflow calls CUSTOM_API_PERMISSION_DENIED return karte hain. Wrong ya revoked tokens API_TOKEN_INVALID return karte hain. Inactive workflows mounted nahi hote.

Register template: Settings / Workflows inactive POST /api/custom/auth/register starter bana sakta hai. Pehle email, passwordHash, aur status fields wala users content schema banao. Template password validate karta hai lekin store nahi karta; production se pehle PASSWORD_HASH_PLACEHOLDER_REPLACE_WITH_SERVER_SIDE_HASHING ko real server-side hashing se replace karo.

TypeScript projects me Admin UI se schema create/change karne ke baad ye chalao:

npm run types

Ye src/apiagex-types.ts generate karta hai jisse RegisterApiagexCustomRoutes me schema slug aur field autocomplete automatic milta hai. Custom routes me apiagex.schemas.getBySlug("products"), apiagex.entries.query("products", options), aur apiagex.entries.create("products", { data }) jaise helpers typed ho jaate hain.

Generated starter README users ko /doc, /readme, aur /adminui par point karta hai, practical owner/schema/entry/role/webhook/realtime flow include karta hai, aur common errors explain karta hai.

Generated docs/README.md generated API shape, access control, webhooks, realtime, relation docs, payloads, populate options, Admin UI entry pickers, aur common errors explain karta hai.

Generated-project test network install ke bina scaffold verify karta hai: temporary project create karta hai, runtime smoke command chalata hai, temporary port/database par Apiagex start karta hai, aur /api/health, /adminui, /doc, plus /readme check karta hai.

Example:

npm create apiagex@latest my-cms
npx create-apiagex my-cms
npx create-apiagex my-cms --language js
npm run build -w create-apiagex
node packages/create-apiagex/dist/index.js my-cms --dry-run
node packages/create-apiagex/dist/index.js my-cms --yes
node packages/create-apiagex/dist/index.js --dry-run

Publish se pehle local workspace test:

npm run build -w create-apiagex
cd newproject
npx create-apiagex my-cms --yes

Scaffold ke baad:

cd my-cms
npm install
npm run dev