Skip to content

cli.md

Latest commit

 

History

History
977 lines (651 loc) · 27 KB

cli.md

File metadata and controls

977 lines (651 loc) · 27 KB
Raw
toc_max_heading_level 4

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import TOCInline from '@theme/TOCInline';

Platformatic CLI

Installation and usage

Install the Platformatic CLI as a dependency for your project:

npm install platformatic
yarn add platformatic
pnpm add platformatic

Once it's installed you can run it with:

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

The Platformatic CLI provides the following 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.
  • deploy - deploy a Platformatic application to the cloud.
  • runtime - start Platformatic Runtime; type platformatic runtime help to know more.
  • start - start a Platformatic application.
  • login - generate a Platformatic login api key.
  • client - generate a Platformatic client.

compile

Compile all typescript plugins.

  $ platformatic compile

This command will compile the TypeScript plugins for each platformatic application.

deploy

Deploys an application to the Platformatic Cloud.

 $ platformatic deploy

Options:

  • -t, --type static/dynamic - The type of the workspace.
  • -c, --config FILE - Specify a configuration file to use.
  • -k, --keys FILE - Specify a path to the workspace keys file.
  • -l --label TEXT - The deploy label. Only for dynamic workspaces.
  • -e --env FILE - The environment file to use. Default: ".env"
  • -s --secrets FILE - The secrets file to use. Default: ".secrets.env"
  • --workspace-id uuid - The workspace id where the application will be deployed.
  • --workspace-key TEXT - The workspace key where the application will be deployed.
  1. To deploy a Platformatic application to the cloud, you should go to the Platformatic cloud dashboard and create a workspace.
  2. Once you have created a workspace, retrieve your workspace id and key from the workspace settings page. Optionally, you can download the provided workspace env file, which you can use with the --keys option.

ℹ️

When deploying an application to a dynamic workspace, specify the deploy --label option. You can find it on your cloud dashboard or you can specify a new one.

If you do not specify an environment file to use with the -e flag, ensure that a default environment file named .env exists.

Deploy a static Platformatic Cloud application.

platformatic deploy \
    -t static \
    -c platformatic.db.json \
    -e .env.prototype \
    --workspace-id=00000000-0000-0000-0000-000000000000 \
    --workspace-key=11111111111111111111111111111111

Deploy a static Platformatic Cloud application with a workspace keys file. The keys file can be downloaded from the Platformatic Console when generating a new API key.

platformatic deploy \
    -t static \
    -c platformatic.db.json \
    -k foo.plt.txt

The foo.plt.txt must contain two variables for the workspace id and workspace API key.

# Contents of foo.plt.txt
PLATFORMATIC_STATIC_WORKSPACE_ID=00000000-0000-0000-0000-000000000000
PLATFORMATIC_STATIC_WORKSPACE_API_KEY=11111111111111111111111111111111

Deploy a dynamic Platformatic Cloud application.

platformatic deploy \
    -t dynamic \
    -c platformatic.db.json \
    -l dev \
    --workspace-id=00000000-0000-0000-0000-000000000000 \
    --workspace-key=11111111111111111111111111111111

gh

Creates a gh action to deploy platformatic services on workspaces.

 $ platformatic gh -t dynamic

Options:

  • -w --workspace ID - The workspace ID where the service will be deployed.
  • -t, --type static/dynamic - The type of the workspace. Defaults to static.
  • -c, --config FILE - Specify a configuration file to use.
  • -b, --build - Build the service before deploying (npm run build).

If not specified, the configuration will be loaded from any of the following, in the current directory.

  • platformatic.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.tml, or
  • platformatic.service.json, or
  • platformatic.service.yml, or
  • platformatic.service.tml

You can find more details about the configuration format here:

login

Generate a Platformatic login api key.

 $ platformatic deploy

Options:

  • -c, --config FILE - Specify a path to a global platformatic config file. Defaults to ~/.platformatic/config.json.
  • --browser - Automatically open default browser. If process stdout is a TTY, the default is true. Otherwise, the default is false.

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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.tml, or
  • platformatic.service.json, or
  • platformatic.service.yml, or
  • platformatic.service.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({})
  })
}

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.
  • --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

composer

platformatic composer <command>

help

Available commands:

  • 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.composer.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.composer.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.composer.json, or
  • platformatic.composer.yml, or
  • platformatic.composer.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.tml

You can find more details about the configuration format here:

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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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 on platformatic.db.schema.json

Your configuration on platformatic.db.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.db.schema.json. This can allow your IDE to add suggestions (f.e. mandatory/missing fields, types, default values) by opening the config in platformatic.db.json. Running platformatic db 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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.db.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.service.json, or
  • platformatic.service.yml, or
  • platformatic.service.tml

You can find more details about the configuration format here:

help

Available commands:

  • 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 on platformatic.service.schema.json

Your configuration on platformatic.service.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.service.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.service.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, then v1, else vX.
  • -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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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.db.json, or
  • platformatic.db.yml, or
  • platformatic.db.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 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.db.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.db.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.