Version: Next

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

info

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; type platformatic db help to know more.
service - start Platformatic Service; type platformatic 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; type platformatic 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 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 is GET.
-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 is false.
-v, --verbose <boolean> - Make the operation more talkative. Default is false.
-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 is info.
-s, --service <string> - The name of the service to stream logs from.
--pretty <boolean> - Pretty print the logs. Default is true.

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, or
platformatic.yml, or
platformatic.tml, or
platformatic.json, or
platformatic.yml, or
platformatic.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 a 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 the serviceId running in the current runtime
--frontend - Generated a browser-compatible client that uses fetch
--full-response - Client will return full response object rather than just the body. Bear in mind that in some cases the full response will be forced (f.e. generating the frontend with an OpenAPI schema that contains an empty response).
--full-request - Client will be called with all parameters wrapped in body, headers and query 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 as string (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 not npm 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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic Composer Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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 not npm 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 roll back 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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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 on platformatic.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 schema
schema 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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic DB Configuration

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, or
platformatic.yml, or
platformatic.tml

You can find more details about the configuration format here:

Platformatic Service Configuration

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 not npm 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.

schema

Update the config schema file:

schema config - update the JSON schema config available on platformatic.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"
  }
}

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 be ts or js. When the command is run, the Platformatic CLI generates -

api.d.ts - A TypeScript module that includes all the OpenAPI-related types.

api.ts or api.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 your platformatic.json is not set to false). You can find more details about the db configuration format here.
CORS must be managed in your Platformatic app (server.cors.origin.regexp in your platformatic.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 service 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 is GET.
-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 is false.
-v, --verbose <boolean> - Make the operation more talkative. Default is false.
-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 is info.
-s, --service <string> - The name of the service to stream logs from.
--pretty <boolean> - Pretty print the logs. Default is true.

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.

Installation and usage​

Commands​

help​

compile​

inject​

logs​

ps​

start​

upgrade​

client​

help​

composer​

create​

help​

openapi schemas fetch​

start​

db​

compile​

create​

help​

migrations apply​

migrations create​

migrations​

schema​

seed​

start​

types​

service​

compile​

create​

help​

schema​

start​

frontend​

runtime​

compile​

help​

start​

start​

ctl​

config​

env​

help​

inject​

logs​

ps​

reload​

restart​

services​

stop​

Installation and usage

Commands

help

compile

inject

logs

ps

start

upgrade

client

help

composer

create

help

openapi schemas fetch

start

db

compile

create

help

migrations apply

migrations create

migrations

schema

seed

start

types

service

compile

create

help

schema

start

frontend

runtime

compile

help

start

start

ctl

config

env

help

inject

logs

ps

reload

restart

services

stop