Developer toolkit for database migrations and backend automation
Note: This tool is still under development and not recommended for production use. APIs may change between versions.
PostKit CLI is a modular toolkit for backend development with the Appri stack. It provides safe database migrations, auth management, and more.
📚 Documentation: https://docs.postkitstack.com/
npm install -g @appritech/postkit| Requirement | Version | Notes |
|---|---|---|
| Node.js | >= 18.0.0 | Required |
| Docker | Latest | Required only when localDbUrl is empty (auto-container mode) |
# Initialize a new project
postkit init
# Start a database migration session
postkit db start
# Preview schema changes
postkit db plan
# Apply changes to local database
postkit db apply
# Commit migrations for deployment
postkit db commit
# Deploy to remote database
postkit db deploy- Safe Database Migrations - Clone remote databases locally, test changes safely, then deploy with confidence
- Modular Architecture - Each feature is a pluggable module (database, auth, and more coming soon)
- Production Ready - Dry-run verification ensures migrations work before touching production
Session-based database migration workflow for PostgreSQL.
Full documentation: DB Module
| Command | Description |
|---|---|
postkit db start |
Clone remote DB to local, start session |
postkit db plan |
Generate schema diff |
postkit db apply |
Apply migration to local DB |
postkit db commit |
Commit session migrations |
postkit db deploy |
Deploy to remote database |
postkit db status |
Show session state |
postkit db abort |
Cancel session |
postkit db remote |
Manage remote databases |
postkit db migration |
Create manual SQL migration |
postkit db infra |
Manage infrastructure SQL |
postkit db seed |
Manage seed data |
Keycloak realm configuration management.
Full documentation: Auth Module
| Command | Description |
|---|---|
postkit auth export |
Export realm from source Keycloak, clean, and save |
postkit auth import |
Import cleaned realm config to target Keycloak |
postkit auth sync |
Export + Import in sequence (full sync) |
All auth commands support:
-f, --force— Skip confirmation prompts-v, --verbose— Enable detailed output
Output is stored in .postkit/auth/:
.postkit/auth/
├── raw/
│ └── {realm}.json # Raw export from source
└── realm/
└── {realm}.json # Cleaned config for import
Full documentation available at: https://docs.postkitstack.com/
Note: This tool is under active development. APIs and commands may change between versions. We recommend pinning to a specific version in production.
PostKit uses two config files — run postkit init to generate both.
postkit.config.json (commit this):
{
"db": {
"schemaPath": "db/schema",
"schema": "public"
}
}postkit.secrets.json (gitignored — contains credentials and all remote config):
{
"db": {
"localDbUrl": "postgres://user:pass@localhost:5432/myapp_local",
"remotes": {
"dev": { "url": "postgres://user:pass@dev-host:5432/myapp", "default": true }
}
}
}Leave
localDbUrlempty to have PostKit automatically spin up a version-matched Docker container for your local database. No PostgreSQL client tools required on your host.
Run `postkit init` to create the `.postkit/` directory structure:
.postkit/ ├── db/ # Database migration state │ ├── session/ │ ├── migrations/ │ └── ... └── auth/ # Auth module output ├── raw/ # Raw exports from source └── realm/ # Cleaned configs for import
## 🌐 Global Options
These options are available to all commands:
| Option | Description |
|--------|-------------|
| `-v, --verbose` | Enable verbose/debug output |
| `--dry-run` | Show what would be done without making changes |
| `--json` | Output results as JSON (for scripting/CI) |
| `-V, --version` | Output version number |
| `-h, --help` | Display help for command |
## 💡 Typical Workflow
```bash
# 1. Add remotes (first time setup)
postkit db remote add dev "postgres://user:pass@dev-host:5432/myapp" --default
postkit db remote add staging "postgres://user:pass@staging-host:5432/myapp"
# 2. Start a session (clones remote DB locally)
postkit db start
# 3. Make schema changes in db/schema/
# 4. Preview changes
postkit db plan
# 5. Test on local clone
postkit db apply
# 6. Commit when ready
postkit db commit
# 7. Deploy to remote
postkit db deploy --remote staging
For more help, see Troubleshooting or open an issue on GitHub.
- npm Package: https://www.npmjs.com/package/@appritech/postkit
- Documentation: https://docs.postkitstack.com/
- GitHub: https://github.com/appritechnologies/postkit
- Issues: https://github.com/appritechnologies/postkit/issues
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
Built with ❤️ by AppriTeam