Command Line Interface (CLI)

The sylk CLI is used to interact with the sylk.build package and build gRPC micro-services. It provides a set of modules and commands that can be used to create, edit, generate, list, and build project resources.

Installation

Sylk CLI can be installed via pip

pip install sylk

Please refer to CLI Installation for a complete guide to install Sylk CLI on your development environment.

Sylk CLI Usage

You can always check your current running sylk CLI version

sylk --version

💡 Help

If you ever getting stuck with the commands of Sylk CLI you can try and display the help messages throughout all the commands listed below

sylk <command> --help

Commands Overview

• sylk login: login to sylk cloud organziation
• sylk registry: interact with sylk's cloud platform API
• sylk weave: create a sylk schema from existing protobuf files
• sylk new: creates a new Sylk project
• sylk generate: generates a new Sylk resource from a specific resource type
• sylk ls: lists Sylk resources and their details, including dependencies and cloud projects
• sylk package: packages a Sylk resource into a new service or package
• sylk edit: edits an existing Sylk resource by adding, removing, or modifying sub-actions
• sylk build: builds the Sylk resources and generates code files
• sylk call: calls a Sylk RPC method using the gRPC protocol
• sylk extend: extends an existing Sylk resource with a new extension
• sylk run: starts the gRPC server with debug mode attached
• sylk configs: displays and/or edits the configurations for a Sylk project.

Commands

login

The login command allows you to authenticate with the sylk.build platform, providing you with access to the sylk registry and other cloud features.

Usage

By running this command you will instruct the installed version of sylk CLI to save to access token verified with the organization id associated with your account.

You can find your organization id and in Sylk Cloud Platform Settings page. Also your access token will be visible at Settings -> API.

sylk login <sylk-organization-id>

Options

The sylk login command is used to log in to the Sylk platform. It takes one required argument, which is the organization ID. Once logged in, the user can perform various actions and operations within that organization's context.

The positional argument for the sylk login command is:

• organization: The ID of the organization that the user wants to log in to. This is a required argument.

registry

The registry command provides a way to interact with the sylk registry, allowing you to browse projects, and manage your own projects.

Usage

Options

Usage: sylk registry [-h] project_id {pull}

The sylk registry command allows you to pull or push a Sylk project from or to a Sylk registry. A Sylk registry is a central place where Sylk projects can be stored and shared among team members.

To use this command, you need to specify the project_id of the project you want to pull or push. The pull subcommand downloads the project from the registry to your local machine, while the push subcommand uploads your local project to the sylk cloud (Currently not available).

Note that before you can push a project to the registry, you need to have the appropriate permissions. You also need to be logged in to the correct organization using the sylk login command.

Sub-commands:

• pull: downloads a Sylk project from the registry to your local machine.

For example to start a new local project from an existing cloud project you can use the sylk new command with the following arguments:

sylk new <project-directory> --project-id <organization-id>.<project-name>

• project-directory: The root project directory which sylk CLI will create and instantiate the new project based on cloud resources.
• organization-id: Your organization id that is provided after login to sylk cloud platform.
• project-name: Tour cloud project name.
  💡 Tip

  You can list your cloud projects and thier respective ID's with running the following command sylk ls --cloud

weave

The sylk weave command is designed to synchronize your local Sylk schema with manually updated Protobuf files, or to "migrate" from local protobuf files to a sylk schema.

Usage

# Update existing sylk schema
sylk weave

# Update Sylk schema based on Protobuf files in a specific directory
sylk weave --proto-path ./path/to/your/proto/directory

# Run a dry-run to see what will be updated without making any changes
sylk weave --proto-path ./path/to/your/proto/directory --dry-run

# Update and build Protobuf files automatically
sylk weave --proto-path ./path/to/your/proto/directory -b

Options

--proto-path: Specify the directory path containing Protobuf files relative to the root project.

--dry-run: Run the command without making any changes to verify what will happen.

-b/--build: Automatically build Protobuf files after the weave operation.

-y/--yes: Automatically confirm all prompts.

✏️ Note

The --dry-run option is useful for checking what will be updated before making any changes.

new/n

The new or n command allows you to create a new sylk project. This command will prompt you for information about your project and generate a new project directory with a basic sylk configuration.

Usage

# Create new sylk project
sylk new some-project-name

# Create new sylk project at the current directory
sylk new in-the-same-dir --path .

# Create new sylk project with options
sylk new some-project \
  --server go \
  --clients go typescript python \
  --code-base pkg \
  --base-protos protos \
  --domain foo

Options

The sylk new command is used to create a new project in the Sylk CLI. Here is a breakdown of its options:

project: The name of the new project you want to create.

-p/--path: The path for the project root directory. By default, the project will be created in the current directory.

--port: The port number on which the Sylk server will run. The default value is 3000.

--host: The hostname for the Sylk server. By default, it is set to localhost.

--domain: The domain name for the project.

-s/--server: The programming language to use for the server. Currently, Sylk supports Python, Node.js and Go see the supported languages section.

-c/--clients: The list of programming languages to use for client-side development. You can specify multiple languages separated by spaces. Currently, Sylk supports Python, JavaScript, Typescript, Webpack, and Go.

--template: Allows you to create a new project based on a template. You can specify the template name and Sylk will generate a new project based on the template.

--project-id: The project ID from the Sylk cloud platform. This is used when you want to create a new project based on a schema from the Sylk cloud platform.

--token: The access token for sylk platform needed if used with --project-id to pull a new project.

--base-protos: The base sub-directory under root project which will hold all protobuf files.

--code-base: The main code base directory.

generate/g

The generate or g command allows you to create new sylk resources, such as messages, enums, and methods. This command will prompt you for information about the resource you wish to create and generate the appropriate files.

Usage

# Generate a new "package" with nested namespaces
sylk generate package hello/world/v1

# Same as
sylk g p hello.world.v1

# Geneare new package without namespaces
sylk g p world

# Generate new "Hello" message under specific package (hello.world.v1)
sylk g m hello/world/v1/Hello

# Generate "HelloWorldService" under (hello.world.v1) package
sylk generate service hello.world.v1.HelloWorldService

# Generate enum and specify a `--tag` (different file from default)
sylk g e WeekDays --tag dates

Options

The sylk generate command is used to create new resources in a Sylk project. It takes the following arguments:

• The type of resource to generate, which can be one of service, package, message, rpc, or enum.
• An optional name for the resource, specified with the -n or --name option.
• An optional parent resource for the new resource, specified with the -p or --parent option.
• An optional --build flag that indicates whether to automatically build the resources after generating them.

The available resource types are:

• service: creates a new service, which is a collection of related functions that can be called remotely.
• package: creates a new package, which is a collection of related services.
• message: creates a new message type, which can be used as a payload for services or RPC calls.
• rpc: creates a new remote procedure call (RPC) service, which allows one service to call a function on another service.
• enum: creates a new enumeration type, which represents a fixed set of possible values for a field or argument.

By default, the new resource will be created in the current directory. If you want to specify a different location, you can use the -p or --path option.

✏️ Note

You can specify a shortand when generating new resources with sylk CLI - You must pass a shortand when using the short for generate as follows:

sylk g <shortand resource>

The available resources names are:

package -> p

service -> s

message -> m

enum -> e

rpc -> r

ls

The ls command allows you to list all available resources in your sylk project, including packages, messages, enums, methods, and more.

Usage

Options

The sylk ls command is used to list resources and their information in the Sylk project. Here are the available options:

• --help: displays the help message and exits.

• --full-name: displays a resource report for a specific resource by passing in a full name. For example, domain.test.GetTest will return GetTest (RPC) which is under test (service).

• -t or --type: lists resources of a specific resource type. Valid values for this option include service, package, message, rpc, enum, and extension.

• -d or --dependencies: lists the dependencies graph for your project. This will show you the resources that your project depends on and the resources that depend on your project.

  ---------------------------------------------
  'Listing Dependencies All'
  ---------------------------------------------
  
  [*] || Service: images
      ||       |
      ||       Package -- sylk.API.v1
      ||           |
      ||               Package -- sylk.Image.v1
      ||       |
      ||       Package -- sylk.Image.v1
      ||           |
      ||               Package -- google.protobuf.Struct
  
  [*] | Package: sylk.Dockerfile.v1
  
  [*] | Package: sylk.Image.v1
      ||       |
      ||        -- google.protobuf.Struct
  
  [*] | Package: sylk.API.v1
      ||       |
      ||        -- sylk.Image.v1
  
  [*] | Package: sylk.Plugin.v1
      ||       |
      ||        -- sylk.Dockerfile.v1

  can be translated as:

• -c or --cloud: lists the cloud project for your Sylk account. This will display the cloud projects that you have created in the Sylk.build cloud platform.

• --templates: lists all available project templates that can be used in:

  sylk new <project> --template <@some/template>

package

The package command allows you to attach a sylk package to your project or another package, allowing you to use the resources defined in that package.

Usage

Options

The sylk package command is used to inject or remove packages into a Sylk service or another package.

Here's how to use sylk package:

The source argument specifies the full name of the package you want to inject or remove. The target argument specifies the full name of the package or the name of the service that you wish to be dependent on the package passed as source argument.

If the -r or --remove option is specified, the package at the target location will be removed.

Here's an example of injecting a package into a Sylk service:

sylk package <domain>.<package>.<version> <service>

❗️ Avoid Circular Dependency

Sylk (and most of other softwares) not supprting for circular dependencies. For situation where a project holds 2 or more packages, for example:

• packageA
• packageB

packageA is dependent on packageB, Sylk's CLI is restricting the user to accidently trying to inject a packageA into packageB which means that packageB cannot be dependent on packageA which is depdent on the same package which trying to make use of, in this case packageB.

This diagram displays the WRONG situation when trying to create a circular dependency:

This diagram however display a VALID situation when trying to create a circular dependency:

This will remove a package called mypackage from myservice

To remove a package, you can use the -r option:

sylk package -r mypackage myservice

edit

The edit command allows you to edit any sylk resource in your project, such as messages, enums, and methods.

Usage

Options

The sylk edit command allows you to edit resources in your Sylk project. Here's an overview of its usage:

• name: The full name of the resource you want to edit.

• -a/--action: The action you want to perform on the resource. It can be one of the following:

  • add: Add a new sub-resource or field to the resource.
  • remove: Remove a sub-resource or field from the resource.
  • modify: Modify an existing sub-resource or field of the resource.

• --sub-actions: Additional sub-actions you want to perform on the resource. The available sub-actions depend on the main action you choose.

Note that to use this command, you need to have the necessary permissions to edit the resource.

template

The template command allows you to create a new sylk project template from your sylk.json, proto files directory, or sylk.template.py.

build

The build command allows you to build your sylk project, generating the necessary source code and configuration files.

Usage

# Build both protobuf files and code (autogenerated+compiled)
sylk build

# Build only protobuf files
sylk build --protos

# Build only autogenerated code (server + clients) and compiled code from exisitng protobuf
sylk build --code

Options

The sylk build command is used to build resources into code files. It has two options:

• --protos: This option builds only the resource protos files without generating code files.

• --code: This option builds only the resource code classes files without generating protos files.

By default, when running the sylk build command without any options, both the protos files and code files are generated.

call

The call command allows you to call a sylk method, providing input parameters and viewing the output of the method call.

Usage

Options

The sylk call command is used to call a remote procedure call (RPC) on a service. Here's a description of its usage:

The service argument is the full path to the service that contains the RPC you want to call. The rpc argument is the name of the RPC you want to call.

The --debug option can be used to print out additional information during the call process for debugging purposes.

The --host and --port options can be used to specify the hostname and port of the service if they are different from the defaults.

The --timeout option can be used to specify a timeout for the RPC call in seconds.

extend

Command is in Beta

The extend command allows you to extend any sylk resource in your project, such as messages, enums, and methods.

Usage

Options

The sylk extend command is used to extend a resource in a Sylk project. This command is used when you want to add functionality to a specific resource. The name argument is the full name of the resource you want to extend.

There is an optional argument --extension which is used to specify the name of the extension resource that will be used to extend the target resource. If this argument is not specified, the command will prompt you to select an extension resource.

For example, if you want to extend an RPC resource named GetUsers in a Sylk project, you can run the following command:

sylk extend myproject.services.UserService.GetUsers --extension myproject.extensions.GetUsersExtension

This command will extend the GetUsers RPC resource in the UserService service with the functionality provided by the GetUsersExtension extension resource.

run

The run command allows you to run the sylk server on your local machine using the current active project.

Usage

# Start a gRPC server with debug log level
sylk run --log-level debug

configs

The configs command allows you to display the sylk build configurations for your project. This includes information about your project's settings, such as the project name and version number.

Options

• -h, --help: show sylk CLI help message and exit.
• -v, --version: Display sylk.build current installed version.
• -e, --expand: Expand optional fields for each resource.
• --loglevel {DEBUG,DEBUG,WARNING,ERROR,CRITICAL}: Log level.
• --verbose: Control on verbose logging.
• -u, --undo: Undo last sylk.json modification.
• -r, --redo: Redo sylk.json modification, if undo has been made.
• --purge: Purge .sylk/contxt.json file.