Platformatic CLI
Installation and usage
Install the Platformatic CLI as a dependency for your project:
- npm
- Yarn
- pnpm
npm install platformatic
yarn add platformatic
pnpm add platformatic
Once it's installed you can run it with:
- npm
- Yarn
- pnpm
npx platformatic
yarn platformatic
pnpm platformatic
The platformatic
package can be installed globally, but installing it as a
project dependency ensures that everyone working on the project is using the
same version of the Platformatic CLI.
Commands
help
Welcome to Platformatic. Available commands are:
help
- display this message.help <command>
- show more information about a command.db
- start Platformatic DB; typeplatformatic db help
to know more.service
- start Platformatic Service; typeplatformatic service help
to know more.upgrade
- upgrade the Platformatic configuration to the latest version.gh
- create a new gh action for Platformatic deployments.runtime
- start Platformatic Runtime; typeplatformatic runtime help
to know more.start
- start a Platformatic application.client
- generate a Platformatic client.ps
- list all Platformatic runtime applications.logs
- stream logs for a Platformatic runtime application.inject
- inject a request into a Platformatic runtime application.ctl
- Platformatic Control commands;platformatic ctl help
to know more.
compile
Compile all typescript plugins.
$ platformatic compile
This command will compile the TypeScript plugins for each platformatic application.
inject
Injects a request to the Platformatic runtime service.
$ platformatic inject -n runtime-name /hello
-X POST
-H "Content-Type: application/json"
-d '{"key": "value"}'
Options:
-p, --pid <number>
- The processid
of the runtime.-n, --name <string>
- The name of the runtime.-s, --service <string>
- The name of the runtime service.-X, --request <string>
- The request HTTP method. Default isGET
.-H, --header <string>
- The request header. Can be used multiple times.-d, --data <string>
- The request data.-i, --include <boolean>
- Include the response headers in the output. Default isfalse
.-v, --verbose <boolean>
- Make the operation more talkative. Default isfalse
.-o, --output <file>
- Write the response to the specified file.
The inject
command sends a request to the runtime service and prints the
response to the standard output. If the --service
option is not specified the
request is sent to the runtime entry point.
The inject
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
logs
Streams logs from the platformatic runtime application.
$ platformatic logs -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.-l, --level <string>
- The pino log level to stream. Default isinfo
.-s, --service <string>
- The name of the service to stream logs from.--pretty <boolean>
- Pretty print the logs. Default istrue
.
If --service
is not specified, the command will stream logs from all services.
The logs
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
ps
Lists all running platformatic runtime applications.
$ platformatic ps
To see the list of all available control commands, run platformatic ctl help
.
The ps
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
start
Start a Platformatic application with the following command:
$ platformatic start
Options:
-c, --config <path>
- Path to the configuration file.--inspect[=[host:]port]
- Start the Node.js debugger.host
defaults to'127.0.0.1'
.port
defaults to 9229. Use caution when binding to a public host:port combination.--inspect-brk[=[host:]port]
- Start the Node.js debugger and block until a client has attached.host
defaults to'127.0.0.1'
.port
defaults to 9229. Use caution when binding to a public host:port combination.
upgrade
Upgrade the Platformatic schema configuration to the latest version.
$ platformatic upgrade
Options:
-c, --config FILE
- Specify a schema configuration file to use.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
, orplatformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
client
platformatic client <command>
help
Create a Fastify plugin that exposes a client for a remote OpenAPI or GraphQL API.
To create a client for a remote OpenAPI API, you can use the following command:
$ platformatic client http://example.com/to/schema/file -n myclient
To create a client for a remote Graphql API, you can use the following command:
$ platformatic client http://example.com/graphql -n myclient
Instead of an URL, you can also use a local file:
$ platformatic client path/to/schema -n myclient
To create a client for a service running in a Platformatic runime use the following command:
$ platformatic client --runtime SERVICE_NAME -n myclient
All the above commands will create a Fastify plugin that exposes a client in the request
object for the remote API in a folder myclient
and a file named myclient.js inside it.
If platformatic config file is specified, it will be edited and a clients
section will be added.
Then, in any part of your Platformatic application, you can use the client.
You can use the client in your application in Javascript, calling a GraphQL endpoint:
module.exports = async function (app, opts) {
app.post('/', async (request, reply) => {
const res = await request.myclient.graphql({
query: 'query { hello }'
})
return res
})
}
or in Typescript, calling an OpenAPI endpoint:
import { FastifyInstance } from 'fastify'
/// <reference path="./myclient" />
export default async function (app: FastifyInstance) {
app.get('/', async (request, reply) => {
return request.myclient.get({})
})
}
You can generate only the types with the --types-only flag.
$ platformatic client http://exmaple.com/to/schema/file --name myclient --types-only
Will create the single myclient.d.ts file.
Options:
-c, --config <path>
- Path to the configuration file.-n, --name <name>
- Name of the client.-f, --folder <name>
- Name of the plugin folder, defaults to --name value.-t, --typescript
- Generate the client plugin in TypeScript.-R, --runtime <serviceId>
- Generate the client for theserviceId
running in the current runtime--frontend
- Generated a browser-compatible client that usesfetch
--full-response
- Client will return full response object rather than just the body.--full-request
- Client will be called with all parameters wrapped inbody
,headers
andquery
properties. Ignored if--frontend
--full
- Enables both--full-request
and--full-response
overriding them.--optional-headers <headers>
- Comma separated string of headers that will be marked as optional in the type file. Ignored if--frontend
--validate-response
- If set, will validate the response body against the schema. Ignored if--frontend
--language js|ts
- Generate a Javascript or Typescript frontend client. Only works if--frontend
--url-auth-headers <stringify-headers>
- When the Open API schema is passed as URL (instead of static file) this property allow to pass authorization headers. Headers should be passed asstring
(e.g.'{"authorization":"42"}'
).--types-only
- Generate only the type file.
composer
platformatic composer <command>
create
Creates a new Platformatic Composer application.
Options are
dir <string>
- the directory where to create the project (Default:process.cwd() + 'platformatic-composer'
)port <string>
- the port where the application will listen (Default:3042
)hostname <string>
- the hostname where the application will listen (Default:0.0.0.0
)git <boolean>
- Init the git repository (Default:true
)typescript <boolean>
- Use Typescript (Default:false
)install <boolean>
- Run or notnpm install
after creating the files (Default:true
)plugin <boolean>
- Creates a sample plugin and tests (Default:true
)
help
Available commands:
create
- creates a new Platformatic Composer application.help
- show this help message.help <command>
- shows more information about a command.start
- start the server.openapi schemas fetch
- fetch OpenAPI schemas from services.
openapi schemas fetch
Fetch OpenAPI schemas from remote services to use in your Platformatic project.
$ platformatic composer openapi schemas fetch
It will fetch all the schemas from the remote services and store them by path
set in the platformatic.json
file. If the path is not set, it will
skip fetching the schema.
start
Start the Platformatic Composer server with the following command:
$ platformatic composer start
You will need a configuration file. Here is an example to get you started,
save the following as platformatic.json
:
{
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"composer": {
"services": [
{
"id": "service1",
"origin": "http://127.0.0.1:3051",
"openapi": {
"url": "/documentation/json"
}
},
{
"id": "service2",
"origin": "http://127.0.0.1:3052",
"openapi": {
"file": "./schemas/service2.openapi.json"
}
}
],
"refreshTimeout": 1000
}
}
By sending the SIGUSR2 signal, the server can be reloaded.
Options:
-c, --config FILE
- Specify a configuration file to use.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
db
platformatic db <command>
compile
Compile typescript plugins.
$ platformatic db compile
As a result of executing this command, the Platformatic DB will compile typescript
plugins in the outDir
directory.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
create
Creates a new Platformatic DB application.
Options are
dir <string>
- the directory where to create the project (Default:process.cwd() + 'platformatic-composer'
)port <string>
- the port where the application will listen (Default:3042
)hostname <string>
- the hostname where the application will listen (Default:0.0.0.0
)connectionString <string>
- the connection string for your database (Default:sqlite://./db.sqlite
)migrations <boolean>
- Creates sample migrations (Default:true
)git <boolean>
- Init the git repository (Default:true
)typescript <boolean>
- Use Typescript (Default:false
)install <boolean>
- Run or notnpm install
after creating the files (Default:true
)plugin <boolean>
- Creates a sample plugin and tests (Default:true
)
help
Available commands:
help
- show this help message.help <command>
- shows more information about a command.start
- start the server.compile
- compile typescript plugins.seed
- run a seed file.types
- generate typescript types for entities.schema
- generate and print api schema.migrations create
- generate do and undo migration files.migrations apply
- apply migration files.
migrations apply
Apply all configured migrations to the database:
$ platformatic db migrations apply
The migrations will be applied in the order they are specified in the
folder defined in the configuration file. If you want to apply a specific migration,
you can use the --to
option:
$ platformatic db migrations apply --to 001
Here is an example migration:
CREATE TABLE graphs (
id SERIAL PRIMARY KEY,
name TEXT
);
You can always rollback to a specific migration with:
$ platformatic db migrations apply --to VERSION
Use 000 to reset to the initial state.
Options:
-c, --config <path>
- Path to the configuration file.-t, --to <version>
- Migrate to a specific version.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
migrations create
Create next migration files.
$ platformatic db migrations create
It will generate do and undo sql files in the migrations folder. The name of the files will be the next migration number.
$ platformatic db migrations create
The migration files are named 001.<do|undo>.sql
, 002.<do|undo>.sql
etc...
Options:
-c, --config <path>
- Path to the configuration file.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
migrations
Available commands:
migrations create
- generate do and undo migration files.migrations apply
- apply migration files.
schema
Update the config schema file:
schema config
- update the JSON schema config available onplatformatic.json
Your configuration on platformatic.json
has a schema defined to improve the developer experience and avoid mistakes when updating the configuration of Platformatic DB.
When you run platformatic db init
, a new JSON $schema
property is added in platformatic.json
. This can allow your IDE to add suggestions (f.e. mandatory/missing fields, types, default values) by opening the config in platformatic.json
.
Running platformatic schema config
you can update your schema so that it matches well the latest changes available on your config.
Generate a schema from the database and prints it to standard output:
schema graphql
- generate the GraphQL schemaschema openapi
- generate the OpenAPI schema
Options:
-c, --config FILE
- Specify a configuration file to use.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
seed
Load a seed into the database. This is a convenience method that loads a JavaScript file and configure @platformatic/sql-mapper to connect to the database specified in the configuration file.
Here is an example of a seed file:
'use strict'
module.exports = async function ({ entities, db, sql }) {
await entities.graph.save({ input: { name: 'Hello' } })
await db.query(sql`
INSERT INTO graphs (name) VALUES ('Hello 2');
`)
}
You can run this using the seed
command:
$ platformatic db seed seed.js
Options:
--config
- Path to the configuration file.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
start
Start the Platformatic DB server with the following command:
$ platformatic db start
You will need a configuration file. Here is an example to get you started,
save the following as platformatic.json
:
{
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"db": {
"connectionString": "sqlite://./db"
},
"migrations": {
"dir": "./migrations"
}
}
Remember to create a migration, run the db help migrate
command to know more.
All outstanding migrations will be applied to the database unless the
migrations.autoApply
configuration option is set to false.
By sending the SIGUSR2 signal, the server can be reloaded.
Options:
-c, --config FILE
- Specify a configuration file to use.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
types
Generate typescript types for your entities from the database.
$ platformatic db types
As a result of executing this command, the Platformatic DB will generate a types
folder with a typescript file for each database entity. It will also generate a
global.d.ts
file that injects the types into the Application instance.
In order to add type support to your plugins, you need to install some additional
dependencies. To do this, copy and run an npm install
command with dependencies
that "platformatic db types" will ask you.
Here is an example of a platformatic plugin.js with jsdoc support. You can use it to add autocomplete to your code.
/// <reference path="./global.d.ts" />
'use strict'
/** @param {import('fastify').FastifyInstance} app */
module.exports = async function (app) {
app.get('/movie', async () => {
const movies = await app.platformatic.entities.movie.find({
where: { title: { eq: 'The Hitchhiker\'s Guide to the Galaxy' } }
})
return movies[0].id
})
}
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
service
platformatic service <command>
compile
Compile typescript plugins.
$ platformatic service compile
As a result of executing this command, Platformatic Service will compile typescript
plugins in the outDir
directory.
Using the --clean
flag, the outDir directory will be removed before the new compilation process starts.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
create
Creates a new Platformatic Service application.
Options are
dir <string>
- the directory where to create the project (Default:process.cwd() + 'platformatic-composer'
)port <string>
- the port where the application will listen (Default:3042
)hostname <string>
- the hostname where the application will listen (Default:0.0.0.0
)git <boolean>
- Init the git repository (Default:true
)typescript <boolean>
- Use Typescript (Default:false
)install <boolean>
- Run or notnpm install
after creating the files (Default:true
)plugin <boolean>
- Creates a sample plugin and tests (Default:true
)
help
Available commands:
create
- creates a new Platformatic Service application.help
- show this help message.help <command>
- show more information about a command.start
- start the server.schema config
- generate the schema configuration file.compile
- compile the typescript files.versions bump
- bump a new version of the API.versions update
- update the latest version of the API.
schema
Update the config schema file:
schema config
- update the JSON schema config available onplatformatic.json
Your configuration on platformatic.json
has a schema defined to improve the developer experience and avoid mistakes when updating the configuration of Platformatic Service.
When you initialize a new Platformatic service (f.e. running npm create platformatic@latest
), a new JSON $schema
property is added in the platformatic.json
config. This can allow your IDE to add suggestions (f.e. mandatory/missing fields, types, default values) by opening the config in platformatic.service.json
.
Running platformatic service schema config
you can update your schema so that it matches well the latest changes available on your config.
start
Start the Platformatic Service with the following command:
$ platformatic service start
You will need a configuration file. Here is an example to get you started,
save the following as platformatic.json
:
{
"server": {
"hostname": "127.0.0.1",
"port": 0,
"logger": {
"level": "info"
}
},
"plugin": {
"path": "./plugin.js"
}
}
versions bump
Bump a new version of platformatic application API.
$ platformatic service versions bump
As a result, a new application API version will be created, and mappers for the previous version will be generated.
Options:
-c, --config <path>
- Path to the configuration file.-v, --version <string>
- The name of the version to bump. Default: if first version, thenv1
, elsevX
.-p, --prefix <string>
- The prefix to use for the new version. Default: if first version, then/v1
, else/vX
.--openai
- Use OpenAI to generate the version mappers plugins. Default: false.--user-api-key <string>
- Platformatic user API key. If not specified, the key will be loaded from the~/.platformatic/config
file.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
versions update
Update the latest version of platformatic application API.
$ platformatic service versions update
As a result, the latest application API version will be updated, and mappers for the previous version will be generated.
Options:
-c, --config <path>
- Path to the configuration file.--openai <boolean>
- Use OpenAI to generate the version mappers plugins. Default: false.--user-api-key <string>
- Platformatic user API key. If not specified, the key will be loaded from the~/.platformatic/config
file.
If not specified, the configuration will be loaded from any of the following, in the current directory.
platformatic.json
, orplatformatic.yml
, orplatformatic.tml
You can find more details about the configuration format here:
frontend
platformatic client <url> --frontend --language <language>
Create frontend code to consume the REST APIs of a Platformatic application.
From the directory you want the frontend code to be generated (typically <YOUR_FRONTEND_APP_DIRECTORY>/src/
) run -
npx platformatic frontend http://127.0.0.1:3042 ts
ℹ️
Where
http://127.0.0.1:3042
must be replaced with your Platformatic application endpoint, and the language can either bets
orjs
. When the command is run, the Platformatic CLI generates -
api.d.ts
- A TypeScript module that includes all the OpenAPI-related types.api.ts
orapi.js
- A module that includes a function for every single REST endpoint.
If you use the --name
option it will create custom file names.
npx platformatic frontend http://127.0.0.1:3042 ts --name foobar
Will create foobar.ts
and foobar-types.d.ts
Refer to the dedicated guide where the full process of generating and consuming the frontend code is described.
In case of problems, please check that:
- The Platformatic app URL is valid.
- The Platformatic app whose URL belongs must be up and running.
- OpenAPI must be enabled (
db.openapi
in yourplatformatic.json
is not set tofalse
). You can find more details about the db configuration format here. - CORS must be managed in your Platformatic app (
server.cors.origin.regexp
in yourplatformatic.json
is set to/*/
, for instance). You can find more details about the cors configuration here.
runtime
platformatic runtime <command>
compile
Compile all typescript plugins for all services.
$ platformatic runtime compile
This command will compile the TypeScript plugins for each services registered in the runtime.
help
Available commands:
help
- show this help message.help <command>
- shows more information about a command.start
- start the application.
start
Start the Platformatic Runtime with the following command:
$ platformatic runtime start
You can also specify a custom routes file, for example:
$ platformatic runtime start routes.js
Where routes.js
is:
module.exports = async function (app) {
app.get('/hello', async () => {
return { hello: 'hello123' }
})
}
start
Start a Platformatic application with the following command:
$ platformatic start
Options:
-c, --config <path>
- Path to the configuration file.--inspect[=[host:]port]
- Start the Node.js debugger.host
defaults to'127.0.0.1'
.port
defaults to 9229. Use caution when binding to a public host:port combination.--inspect-brk[=[host:]port]
- Start the Node.js debugger and block until a client has attached.host
defaults to'127.0.0.1'
.port
defaults to 9229. Use caution when binding to a public host:port combination.
ctl
platformatic ctl <command>
config
Prints runtime or runtime service config file
$ platformatic ctl config -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.
The config
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
env
Lists platformatic runtime application environment variables
$ platformatic ctl env -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.
The env
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
help
Available commands:
ps
- lists all platformatic runtime applications.stop
- stops a platformatic runtime application.restart
- restarts all platformatic runtime services.reload
- reloads all platformatic runtime services.services
- lists the runtime services.config
- prints runtime or runtime service config file.env
- lists the runtime environment variables.logs
- shows the runtime logs.inject
- injects a request to the runtime service.
inject
Injects a request to the platformatic runtime service.
$ platformatic ctl inject -n runtime-name /hello
-X POST
-H "Content-Type: application/json"
-d '{"key": "value"}'
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.-s, --service <string>
- The name of the runtime service.-X, --request <string>
- The request HTTP method. Default isGET
.-H, --header <string>
- The request header. Can be used multiple times.-d, --data <string>
- The request data.-i, --include <boolean>
- Include the response headers in the output. Default isfalse
.-v, --verbose <boolean>
- Make the operation more talkative. Default isfalse
.-o, --output <file>
- Write the response to the specified file.
The inject
command sends a request to the runtime service and prints the
response to the standard output. If the --service
option is not specified the
request is sent to the runtime entrypoint.
The inject
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
logs
Streams logs from the platformatic runtime application.
$ platformatic ctl logs -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.-l, --level <string>
- The pino log level to stream. Default isinfo
.-s, --service <string>
- The name of the service to stream logs from.--pretty <boolean>
- Pretty print the logs. Default istrue
.
If --service
is not specified, the command will stream logs from all services.
The logs
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
ps
Lists all running platformatic runtime applications.
$ platformatic ctl ps
To see the list of all available control commands, run platformatic ctl help
.
The ps
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
reload
Reloads a platformatic runtime application.
$ platformatic ctl reload -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime to reload.-n, --name <string>
- The name of the runtime to reload.
The difference between reload
and restart
is that reload
does not kill
the runtime process. It stops and starts all the runtime services.
The reload
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
restart
Restarts a platformatic runtime application.
$ platformatic ctl restart -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime to restart.-n, --name <string>
- The name of the runtime to restart.
The restart
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
services
Lists the platformatic runtime services.
$ platformatic ctl services -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime.-n, --name <string>
- The name of the runtime.
The services
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.
stop
Stops a platformatic runtime application.
$ platformatic ctl stop -n runtime-name
Options:
-p, --pid <number>
- The process id of the runtime to stop.-n, --name <string>
- The name of the runtime to stop.
The stop
command uses the Platformatic Runtime Management API. To enable it
set the managementApi
option to true
in the runtime configuration file.
To get the list of runtimes with enabled management API use the
platformatic ctl ps
command.