Skip to content

Latest commit

 

History

History
726 lines (533 loc) · 25.7 KB

usage.md

File metadata and controls

726 lines (533 loc) · 25.7 KB
Raw
title weight
Usage
40

The AsyncAPI CLI makes it easier to work with AsyncAPI documents.

Usage

$ npm install -g @asyncapi/cli
$ asyncapi COMMAND
running command...
$ asyncapi (--version)
@asyncapi/cli/0.58.7 linux-x64 node-v18.18.0
$ asyncapi --help [COMMAND]
USAGE
  $ asyncapi COMMAND
...

Commands

asyncapi bundle

bundle one or multiple asyncapi documents and their references together.

USAGE
  $ asyncapi bundle [-h] [-o <value>] [-r] [-b <value>]

FLAGS
  -b, --base=<value>               Path to the file which will act as a base. This is required when some properties are
                                   to needed to be overwritten.
  -h, --help                       Show CLI help.
  -o, --output=<value>             The output file name. Omitting this flag the result will be printed in the console.
  -r, --reference-into-components  Bundle the message $refs into components object.

DESCRIPTION
  bundle one or multiple asyncapi documents and their references together.

EXAMPLES
  $ asyncapi bundle ./asyncapi.yaml > final-asyncapi.yaml

  $ asyncapi bundle ./asyncapi.yaml --output final-asyncapi.yaml

  $ asyncapi bundle ./asyncapi.yaml ./features.yaml --reference-into-components

  $ asyncapi bundle ./asyncapi.yaml ./features.yaml --base ./asyncapi.yaml --reference-into-components

See code: src/commands/bundle.ts

asyncapi config

CLI config settings

USAGE
  $ asyncapi config

DESCRIPTION
  CLI config settings

See code: src/commands/config/index.ts

asyncapi config context

Manage short aliases for full paths to AsyncAPI documents

USAGE
  $ asyncapi config context

DESCRIPTION
  Manage short aliases for full paths to AsyncAPI documents

See code: src/commands/config/context/index.ts

asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH

Add a context to the store

USAGE
  $ asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH [-h] [-s]

ARGUMENTS
  CONTEXT-NAME    context name
  SPEC-FILE-PATH  file path of the spec file

FLAGS
  -h, --help         Show CLI help.
  -s, --set-current  Set context being added as the current context

DESCRIPTION
  Add a context to the store

See code: src/commands/config/context/add.ts

asyncapi config context current

Shows the current context that is being used

USAGE
  $ asyncapi config context current [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Shows the current context that is being used

See code: src/commands/config/context/current.ts

asyncapi config context edit CONTEXT-NAME NEW-SPEC-FILE-PATH

Edit a context in the store

USAGE
  $ asyncapi config context edit CONTEXT-NAME NEW-SPEC-FILE-PATH [-h]

ARGUMENTS
  CONTEXT-NAME        context name
  NEW-SPEC-FILE-PATH  new file path of the spec file

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Edit a context in the store

See code: src/commands/config/context/edit.ts

asyncapi config context init [CONTEXT-FILE-PATH]

Initialize context

USAGE
  $ asyncapi config context init [CONTEXT-FILE-PATH] [-h]

ARGUMENTS
  CONTEXT-FILE-PATH  Specify directory in which context file should be created:
                     - current directory          : asyncapi config context init . (default)
                     - root of current repository : asyncapi config context init ./
                     - user's home directory      : asyncapi config context init ~

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Initialize context

See code: src/commands/config/context/init.ts

asyncapi config context list

List all the stored contexts in the store

USAGE
  $ asyncapi config context list [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  List all the stored contexts in the store

See code: src/commands/config/context/list.ts

asyncapi config context remove CONTEXT-NAME

Delete a context from the store

USAGE
  $ asyncapi config context remove CONTEXT-NAME [-h]

ARGUMENTS
  CONTEXT-NAME  Name of the context to delete

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Delete a context from the store

See code: src/commands/config/context/remove.ts

asyncapi config context use CONTEXT-NAME

Set a context as current

USAGE
  $ asyncapi config context use CONTEXT-NAME [-h]

ARGUMENTS
  CONTEXT-NAME  name of the saved context

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Set a context as current

See code: src/commands/config/context/use.ts

asyncapi config versions

Show versions of AsyncAPI tools used

USAGE
  $ asyncapi config versions [-h]

FLAGS
  -h, --help  Show CLI help.

DESCRIPTION
  Show versions of AsyncAPI tools used

See code: src/commands/config/versions.ts

asyncapi convert [SPEC-FILE]

Convert asyncapi documents older to newer versions

USAGE
  $ asyncapi convert [SPEC-FILE] [-h] [-o <value>] [-t <value>]

ARGUMENTS
  SPEC-FILE  spec path, url, or context-name

FLAGS
  -h, --help                    Show CLI help.
  -o, --output=<value>          path to the file where the result is saved
  -t, --target-version=<value>  [default: 3.0.0] asyncapi version to convert to

DESCRIPTION
  Convert asyncapi documents older to newer versions

See code: src/commands/convert.ts

asyncapi diff OLD NEW

Find diff between two asyncapi files

USAGE
  $ asyncapi diff OLD NEW [-h] [-f json|yaml|yml|md] [-t breaking|non-breaking|unclassified|all]
    [--markdownSubtype json|yaml|yml] [-o <value>] [--no-error] [-w] [--log-diagnostics] [--diagnostics-format
    json|stylish|junit|html|text|teamcity|pretty] [--fail-severity error|warn|info|hint]

ARGUMENTS
  OLD  old spec path, URL or context-name
  NEW  new spec path, URL or context-name

FLAGS
  -f, --format=<option>
      [default: yaml] format of the output
      <options: json|yaml|yml|md>

  -h, --help
      Show CLI help.

  -o, --overrides=<value>
      path to JSON file containing the override properties

  -t, --type=<option>
      [default: all] type of the output
      <options: breaking|non-breaking|unclassified|all>

  -w, --watch
      Enable watch mode

  --diagnostics-format=(json|stylish|junit|html|text|teamcity|pretty)
      [default: stylish] format to use for validation diagnostics

  --fail-severity=(error|warn|info|hint)
      [default: error] diagnostics of this level or above will trigger a failure exit code

  --[no-]log-diagnostics
      log validation diagnostics or not

  --markdownSubtype=<option>
      the format of changes made to AsyncAPI document. It works only when diff is generated using md type. For example,
      when you specify subtype as json, then diff information in markdown is dumped as json structure.
      <options: json|yaml|yml>

  --no-error
      don't show error on breaking changes

DESCRIPTION
  Find diff between two asyncapi files

See code: src/commands/diff.ts

asyncapi generate

Generate typed models or other things like clients, applications or docs using AsyncAPI Generator templates.

USAGE
  $ asyncapi generate

DESCRIPTION
  Generate typed models or other things like clients, applications or docs using AsyncAPI Generator templates.

See code: src/commands/generate/index.ts

asyncapi generate fromTemplate ASYNCAPI TEMPLATE

Generates whatever you want using templates compatible with AsyncAPI Generator.

USAGE
  $ asyncapi generate fromTemplate ASYNCAPI TEMPLATE [-h] [-d <value>] [-i] [--debug] [-n <value>] [-o <value>]
    [--force-write] [-w] [-p <value>] [--map-base-url <value>]

ARGUMENTS
  ASYNCAPI  - Local path, url or context-name pointing to AsyncAPI file
  TEMPLATE  - Name of the generator template like for example @asyncapi/html-template or
            https://github.com/asyncapi/html-template

FLAGS
  -d, --disable-hook=<value>...  Disable a specific hook type or hooks from a given hook type
  -h, --help                     Show CLI help.
  -i, --install                  Installs the template and its dependencies (defaults to false)
  -n, --no-overwrite=<value>...  Glob or path of the file(s) to skip when regenerating
  -o, --output=<value>           Directory where to put the generated files (defaults to current directory)
  -p, --param=<value>...         Additional param to pass to templates
  -w, --watch                    Watches the template directory and the AsyncAPI document, and re-generate the files
                                 when changes occur. Ignores the output directory.
  --debug                        Enable more specific errors in the console
  --force-write                  Force writing of the generated files to given directory even if it is a git repo with
                                 unstaged files or not empty dir (defaults to false)
  --map-base-url=<value>         Maps all schema references from base url to local folder

DESCRIPTION
  Generates whatever you want using templates compatible with AsyncAPI Generator.

EXAMPLES
  $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-write

See code: src/commands/generate/fromTemplate.ts

asyncapi generate models LANGUAGE FILE

Generates typed models

USAGE
  $ asyncapi generate models LANGUAGE FILE [-h] [-o <value>] [--tsModelType class|interface] [--tsEnumType
    enum|union] [--tsModuleSystem ESM|CJS] [--tsIncludeComments] [--tsExportType default|named] [--tsJsonBinPack]
    [--tsMarshalling] [--tsExampleInstance] [--packageName <value>] [--namespace <value>] [--csharpAutoImplement]
    [--csharpNewtonsoft] [--csharpArrayType Array|List] [--csharpHashcode] [--csharpEqual] [--csharpSystemJson]
    [--log-diagnostics] [--diagnostics-format json|stylish|junit|html|text|teamcity|pretty] [--fail-severity
    error|warn|info|hint]

ARGUMENTS
  LANGUAGE  (typescript|csharp|golang|java|javascript|dart|python|rust|kotlin|php|cplusplus) The language you want the
            typed models generated for.
  FILE      Path or URL to the AsyncAPI document, or context-name

FLAGS
  -h, --help                                                           Show CLI help.
  -o, --output=<value>                                                 The output directory where the models should be
                                                                       written to. Omitting this flag will write the
                                                                       models to `stdout`.
  --csharpArrayType=<option>                                           [default: Array] C# specific, define which type
                                                                       of array needs to be generated.
                                                                       <options: Array|List>
  --csharpAutoImplement                                                C# specific, define whether to generate
                                                                       auto-implemented properties or not.
  --csharpEqual                                                        C# specific, generate the models with the Equal
                                                                       method overwritten
  --csharpHashcode                                                     C# specific, generate the models with the
                                                                       GetHashCode method overwritten
  --csharpNewtonsoft                                                   C# specific, generate the models with newtonsoft
                                                                       serialization support
  --csharpSystemJson                                                   C# specific, generate the models with
                                                                       System.Text.Json serialization support
  --diagnostics-format=(json|stylish|junit|html|text|teamcity|pretty)  [default: stylish] format to use for validation
                                                                       diagnostics
  --fail-severity=(error|warn|info|hint)                               [default: error] diagnostics of this level or
                                                                       above will trigger a failure exit code
  --[no-]log-diagnostics                                               log validation diagnostics or not
  --namespace=<value>                                                  C#, C++ and PHP specific, define the namespace to
                                                                       use for the generated models. This is required
                                                                       when language is `csharp`,`c++` or `php`.
  --packageName=<value>                                                Go, Java and Kotlin specific, define the package
                                                                       to use for the generated models. This is required
                                                                       when language is `go`, `java` or `kotlin`.
  --tsEnumType=<option>                                                [default: enum] TypeScript specific, define which
                                                                       type of enums needs to be generated.
                                                                       <options: enum|union>
  --tsExampleInstance                                                  Typescript specific, generate example of the
                                                                       model
  --tsExportType=<option>                                              [default: default] TypeScript specific, define
                                                                       which type of export needs to be generated.
                                                                       <options: default|named>
  --tsIncludeComments                                                  TypeScript specific, if enabled add comments
                                                                       while generating models.
  --tsJsonBinPack                                                      TypeScript specific, define basic support for
                                                                       serializing to and from binary with jsonbinpack.
  --tsMarshalling                                                      TypeScript specific, generate the models with
                                                                       marshalling functions.
  --tsModelType=<option>                                               [default: class] TypeScript specific, define
                                                                       which type of model needs to be generated.
                                                                       <options: class|interface>
  --tsModuleSystem=<option>                                            [default: ESM] TypeScript specific, define the
                                                                       module system to be used.
                                                                       <options: ESM|CJS>

DESCRIPTION
  Generates typed models

See code: src/commands/generate/models.ts

asyncapi new

Creates a new asyncapi file

USAGE
  $ asyncapi new [-h] [-n <value>] [-e <value>] [-s] [-p <value>] [--no-tty]

FLAGS
  -e, --example=<value>
      name of the example to use. Available examples are:
      - simple.yml
      - anyof.yml
      - application-headers.yml
      - correlation-id.yml
      - websocket-gemini.yml
      - gitter-streaming.yml
      - mercure.yml
      - not.yml
      - operation-security.yml
      - oneof.yml
      - rpc-client.yml
      - rpc-server.yml
      - slack-rtm.yml
      - tutorial.yml
      - streetlights-kafka.yml
      - streetlights-operation-security.yml
      - streetlights-mqtt.yml

  -h, --help
      Show CLI help.

  -n, --file-name=<value>
      name of the file

  -p, --port=<value>
      port in which to start Studio

  -s, --studio
      open in Studio

  --no-tty
      do not use an interactive terminal

DESCRIPTION
  Creates a new asyncapi file

EXAMPLES
  $ asyncapi new	 - start creation of a file in interactive mode

  $ asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty	 - create a new file with a specific name, using one of the examples and without interactive mode

See code: src/commands/new/index.ts

asyncapi new file

Creates a new asyncapi file

USAGE
  $ asyncapi new file [-h] [-n <value>] [-e <value>] [-s] [-p <value>] [--no-tty]

FLAGS
  -e, --example=<value>
      name of the example to use. Available examples are:
      - simple.yml
      - anyof.yml
      - application-headers.yml
      - correlation-id.yml
      - websocket-gemini.yml
      - gitter-streaming.yml
      - mercure.yml
      - not.yml
      - operation-security.yml
      - oneof.yml
      - rpc-client.yml
      - rpc-server.yml
      - slack-rtm.yml
      - tutorial.yml
      - streetlights-kafka.yml
      - streetlights-operation-security.yml
      - streetlights-mqtt.yml

  -h, --help
      Show CLI help.

  -n, --file-name=<value>
      name of the file

  -p, --port=<value>
      port in which to start Studio

  -s, --studio
      open in Studio

  --no-tty
      do not use an interactive terminal

DESCRIPTION
  Creates a new asyncapi file

EXAMPLES
  $ asyncapi new	 - start creation of a file in interactive mode

  $ asyncapi new --file-name=my-asyncapi.yml --example=default-example.yml --no-tty	 - create a new file with a specific name, using one of the examples and without interactive mode

See code: src/commands/new/file.ts

asyncapi new glee

Creates a new Glee project

USAGE
  $ asyncapi new glee [-h] [-n <value>]

FLAGS
  -h, --help          Show CLI help.
  -n, --name=<value>  [default: project] name of the project

DESCRIPTION
  Creates a new Glee project

See code: src/commands/new/glee.ts

asyncapi new project

Creates a new Glee project

USAGE
  $ asyncapi new project [-h] [-n <value>]

FLAGS
  -h, --help          Show CLI help.
  -n, --name=<value>  [default: project] name of the project

DESCRIPTION
  Creates a new Glee project

See code: src/commands/new/project.ts

asyncapi optimize [SPEC-FILE]

optimize asyncapi specification file

USAGE
  $ asyncapi optimize [SPEC-FILE] [-h] [-p remove-components|reuse-components|move-to-components] [-o
    terminal|new-file|overwrite] [--no-tty]

ARGUMENTS
  SPEC-FILE  spec path, url, or context-name

FLAGS
  -h, --help                      Show CLI help.
  -o, --output=<option>           [default: terminal] select where you want the output.
                                  <options: terminal|new-file|overwrite>
  -p, --optimization=<option>...  [default: remove-components,reuse-components,move-to-components] select the type of
                                  optimizations that you want to apply.
                                  <options: remove-components|reuse-components|move-to-components>
  --no-tty                        do not use an interactive terminal

DESCRIPTION
  optimize asyncapi specification file

EXAMPLES
  $ asyncapi optimize ./asyncapi.yaml

  $ asyncapi optimize ./asyncapi.yaml --no-tty

  $ asyncapi optimize ./asyncapi.yaml --optimization=remove-components,reuse-components,move-to-components --no-tty

  $ asyncapi optimize ./asyncapi.yaml --optimization=remove-components,reuse-components,move-to-components --output=terminal --no-tty

See code: src/commands/optimize.ts

asyncapi start

Start asyncapi studio

USAGE
  $ asyncapi start

DESCRIPTION
  Start asyncapi studio

See code: src/commands/start/index.ts

asyncapi start studio

starts a new local instance of Studio

USAGE
  $ asyncapi start studio [-h] [-f <value>] [-p <value>]

FLAGS
  -f, --file=<value>  path to the AsyncAPI file to link with Studio
  -h, --help          Show CLI help.
  -p, --port=<value>  port in which to start Studio

DESCRIPTION
  starts a new local instance of Studio

See code: src/commands/start/studio.ts

asyncapi validate [SPEC-FILE]

validate asyncapi file

USAGE
  $ asyncapi validate [SPEC-FILE] [-h] [-w] [--log-diagnostics] [--diagnostics-format
    json|stylish|junit|html|text|teamcity|pretty] [--fail-severity error|warn|info|hint]

ARGUMENTS
  SPEC-FILE  spec path, url, or context-name

FLAGS
  -h, --help                                                           Show CLI help.
  -w, --watch                                                          Enable watch mode
  --diagnostics-format=(json|stylish|junit|html|text|teamcity|pretty)  [default: stylish] format to use for validation
                                                                       diagnostics
  --fail-severity=(error|warn|info|hint)                               [default: error] diagnostics of this level or
                                                                       above will trigger a failure exit code
  --[no-]log-diagnostics                                               log validation diagnostics or not

DESCRIPTION
  validate asyncapi file

See code: src/commands/validate.ts