Documentation / Reference

Commands

Every command, as the binary declares it. This page is generated from --help on each build of the site: it cannot describe an option the command does not have, nor miss one just added to it.

$ cargo install crabster-cli      # nothing is published yet
$ cargo run -p crabster-cli -- …  # from a clone, in the meantime

Overview🔗

Common options🔗

They hold for every command.

{% raw %}

Generate production-ready Rust backend applications from a domain model

Usage: crabster <COMMAND>

Commands:
  new         Create a new project
  apply       Bring a project into line with a model that changed
  import-cdl  Generate a project from a CDL domain model
  introspect  Write a `.cdl` from a database that already exists
  record      Add a record to a project Crabster generated
  upgrade     Move a project onto the templates this generator ships
  blueprint   Write, check, or read the contract of a blueprint
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

{% endraw %}

crabster new🔗

Create a project. Create a new project

The command, its arguments and its options:

{% raw %}

Create a new project

Usage: crabster new [OPTIONS] [NAME]

Arguments:
  [NAME]
          Name of the project, used as the crate name
          
          Asked for when it is left out and there is a terminal to ask.

Options:
      --path <DIR>
          Directory to generate into [default: ./NAME]

      --database <DATABASE>
          Database the project will use [default: postgres]
          
          The default is not declared to clap, because clap would then supply it and this command could no longer tell "left out" from "asked for explicitly" — which is what decides whether the question is put.
          
          [possible values: postgres, mysql, sqlite]

      --port <PORT>
          Port the generated server listens on [default: 8080]

      --architecture <ARCHITECTURE>
          One application, or several behind a gateway [default: monolith]
          
          `microservices` generates a system: one project per service, a root that starts all of them, and the model they were built from. It is the same system `crabster import-cdl` builds from that model — this command writes the `.cdl` rather than asking you to.
          
          [possible values: monolith, microservices]

      --service <NAME[:DB[:PORT]]>
          A service of a microservices system: `NAME[:DATABASE[:PORT]]`
          
          Repeatable, and only meaningful with `--architecture microservices`. `orders`, `orders:sqlite` and `orders:sqlite:8101` are all valid; what is left out is what the questions would have suggested.

      --gateway <NAME[:PORT]>
          Put a gateway in front of them: `NAME[:PORT]`
          
          The one project in the system that persists nothing. It forwards `/api/<segment>` to whichever service owns that segment.

      --auth <AUTH>
          Accounts and sessions this project owns [default: none]
          
          `jwt` generates an accounts table, a password hash, `/auth/register`, `/auth/login` and the extractor a handler takes to require one. It needs a model — every module here generates against the records — so it implies one: `--record`, or a question in its place.
          
          [possible values: jwt]

      --ui <UI>
          A front end over the generated typed client [default: none]
          
          One of the three UI blueprints shipped in this binary. Each is one page per record, so it implies a model in the same way `--auth` does — and it pulls in the TypeScript client it is written against, whether or not you asked for one.
          
          [possible values: react, vue, angular]

      --record <NAME>
          A first record to start the model from: `--record Task`
          
          One record with one `label: Text` field, which is a place to start rather than a guess at your domain: edit the `.cdl` this writes and run `crabster apply`, or add the next one with `crabster record`.
          
          What it really does is give `--auth` and `--ui` something to generate against. A project with no record has no endpoint to protect and no page to show.

      --discovery <DISCOVERY>
          Register the services with a catalogue [default: none]
          
          [possible values: none, consul]

      --telemetry <TELEMETRY>
          Export spans to a collector [default: none]
          
          [possible values: none, otlp]

      --no-input
          Answer nothing and ask nothing: take the defaults
          
          Questions are already skipped when the input is not a terminal, so a pipe or a CI runner needs nothing. This is for a terminal where you would rather not be asked.

      --with <MODULE>
          Generate this module too, whatever the model asks for
          
          For trying a module before writing the setting that turns it on.

      --without <MODULE>
          Leave this module out, whatever the model asks for

      --blueprint <DIR>
          Blueprint directory whose modules override the built-in ones

      --check
          Run `cargo check` on the result before reporting success
          
          Off by default: it compiles the whole dependency tree, which turns a sub-second command into a minute-long one.

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster import-cdl🔗

Generate from a model. Generate a project from a CDL domain model

The command, its arguments and its options:

{% raw %}

Generate a project from a CDL domain model

Usage: crabster import-cdl [OPTIONS] <FILE>

Arguments:
  <FILE>
          The `.cdl` file describing the domain

Options:
      --path <DIR>
          Directory to generate into [default: the name in the `service` block]

      --database <DATABASE>
          Override the database the model declares
          
          [possible values: postgres, mysql, sqlite]

      --port <PORT>
          Override the port the model declares

      --with <MODULE>
          Generate this module too, whatever the model asks for
          
          For trying a module before writing the setting that turns it on.

      --without <MODULE>
          Leave this module out, whatever the model asks for

      --blueprint <DIR>
          Blueprint directory whose modules override the built-in ones

      --check
          Run `cargo check` on the result before reporting success
          
          Off by default: it compiles the whole dependency tree, which turns a sub-second command into a minute-long one.

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster record🔗

Add a record. Add a record to a project Crabster generated

The command, its arguments and its options:

{% raw %}

Add a record to a project Crabster generated

Usage: crabster record [OPTIONS] --field <CDL> <NAME>

Arguments:
  <NAME>
          Name of the record, in `PascalCase`

Options:
      --field <CDL>
          A field, written exactly as it would be in a `.cdl`
          
          Repeat for each one: `--field "total: Decimal"` `--field "customer: ref Customer"` `--field "note: Text?"`.

      --filterable
          Let list endpoints filter on this record's fields

      --path <DIR>
          The generated project to add to [default: the current directory]

      --blueprint <DIR>
          Blueprint directory whose modules override the built-in ones

      --force
          Overwrite files that were edited after they were generated

      --check
          Run `cargo check` on the result before reporting success

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster apply🔗

Apply a changed model. Bring a project into line with a model that changed

The command, its arguments and its options:

{% raw %}

Bring a project into line with a model that changed

Usage: crabster apply [OPTIONS] [FILE]

Arguments:
  [FILE]
          The `.cdl` describing the domain as it should now be
          
          Defaults to `.crabster/model.cdl`, so editing the model the project records is the ordinary way to ask for one more field. Name a file instead if you keep your `.cdl` elsewhere.
          
          What the difference is measured against is neither: it is `.crabster/applied.cdl`, the model the migrations have actually built. Leave that one alone — it is the only record of what the database has been told.

Options:
      --path <DIR>
          The generated project to change [default: the current directory]

      --dry-run
          Say what would change, and write nothing

      --default <RECORD.FIELD=VALUE>
          What to put in the rows that already exist, for a column that must have a value
          
          Repeat for each one: `--default "Customer.nickname=unknown"`.

      --force
          Allow the changes that destroy data
          
          Dropping a field takes its column, and dropping a record takes its whole table. Nothing here brings either back.

      --blueprint <DIR>
          Blueprint directory whose modules override the built-in ones
          
          Pass the same one the project was generated with.

      --check
          Run `cargo check` on the result before reporting success

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster upgrade🔗

Cross a templates version. Move a project onto the templates this generator ships

The command, its arguments and its options:

{% raw %}

Move a project onto the templates this generator ships

Usage: crabster upgrade [OPTIONS]

Options:
      --path <DIR>
          The generated project to upgrade [default: the current directory]

      --dry-run
          Say what would change, and write nothing

      --force
          Rewrite the files you edited, too
          
          Not the way to use this. Without it, a file you edited is left exactly as it is and the new version is put in `.crabster/incoming/` beside it.

      --blueprint <DIR>
          Blueprint directory whose modules override the built-in ones
          
          Pass the same one the project was generated with.

      --check
          Run `cargo check` on the result before reporting success

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster introspect🔗

Start from an existing database. Write a .cdl from a database that already exists

The command, its arguments and its options:

{% raw %}

Write a `.cdl` from a database that already exists

Usage: crabster introspect [OPTIONS] <URL>

Arguments:
  <URL>
          The database to read: `postgres://…`, `mysql://…`, `sqlite://…`
          
          The only command in Crabster that connects to one. Everything else computes from the model, and the generated project is what runs a migration — here the schema *is* the input, and nothing but the database has it.

Options:
      --out <FILE>
          Where to write the `.cdl` [default: standard output]

      --service <NAME>
          Name the `service` block after this
          
          Left out, no block is written: a port, a database and an authentication module describe a deployment rather than a schema, and inventing them would be inventing decisions.

  -h, --help
          Print help (see a summary with '-h')

{% endraw %}

crabster blueprint🔗

Write and check a blueprint. Write, check, or read the contract of a blueprint

The command, its arguments and its options:

{% raw %}

Write, check, or read the contract of a blueprint

Usage: crabster blueprint <COMMAND>

Commands:
  new       Write a blueprint that works, to change rather than to start from
  check     Say whether a blueprint's modules load and name things that exist
  contract  Print what a blueprint may be written against
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

{% endraw %}

crabster blueprint new🔗

Write a blueprint that works, to change rather than to start from

{% raw %}

Write a blueprint that works, to change rather than to start from

Usage: crabster blueprint new [OPTIONS] <DIR>

Arguments:
  <DIR>  Directory to write the blueprint into. It must not exist

Options:
      --module <NAME>  What the module is called, and the directory inside the blueprint [default: my-module]
  -h, --help           Print help

{% endraw %}

crabster blueprint check🔗

Say whether a blueprint's modules load and name things that exist

{% raw %}

Say whether a blueprint's modules load and name things that exist

Usage: crabster blueprint check <DIR>

Arguments:
  <DIR>  The blueprint directory

Options:
  -h, --help  Print help

{% endraw %}

crabster blueprint contract🔗

Print what a blueprint may be written against

{% raw %}

Print what a blueprint may be written against

Usage: crabster blueprint contract

Options:
  -h, --help  Print help

{% endraw %}