github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

Docs/more improvements (#1292)

Browse Source 
* WIP creating a CLI section

* WIP adding more CLI commands in a new section

* New CLI section with introduction and more CLI commands

* More improvement to the CLI options

* Each CLI command has its own page

* fixed broken links

* Removed outdated copy
This commit is contained in:
James Ritchie
2024-09-11 17:14:39 +01:00
committed by GitHub
parent 47ca24aab8
commit 972b5e34b8
18 changed files with 560 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli-deploy-commands.mdx
+9
View File
@@ -0,0 +1,9 @@
---
title: "CLI deploy options"
sidebarTitle: "Deploy"
description: "Use these options to help deploy your tasks to Trigger.dev."
---
import CliDeployCommands from '/snippets/cli-commands-deploy.mdx';
<CliDeployCommands/>
docs/cli-deploy.mdx
+2 -84
View File
@@ -4,90 +4,8 @@ description: "The `trigger.dev deploy` command can be used to manually deploy."
---
import ComingSoon from '/snippets/coming-soon-generic.mdx';
import CliDeployCommands from '/snippets/cli-commands-deploy.mdx';
You run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta deploy
```
```bash pnpm
pnpm dlx trigger.dev@beta deploy
```
```bash yarn
yarn dlx trigger.dev@beta deploy
```
</CodeGroup>
<Warning>Will fail in CI if any version mismatches are detected. Ensure everything runs locally first using the [dev](/cli-dev) command and don't bypass the version checks!</Warning>
It performs a few steps to deploy:
1. Optionally updates packages when running locally.
2. Typechecks the code.
3. Compiles and bundles the code.
4. Checks that [environment variables](/deploy-environment-variables) are set.
5. Deploys the code to the cloud.
6. Registers the tasks as a new version in the environment (prod by default).
You can also setup [GitHub Actions](/github-actions) to deploy your tasks automatically.
## Options
### Environment `--env` or `-e`
Defaults to `prod` but you can specify `staging`.
### Skip typecheck `--skip-typecheck` or `-T`
Skips the pre-build typecheck step.
### Build platform `--build-platform`
The platform to build the deployment image for. Defaults to `linux/amd64`.
### Log level `--log-level` or `-l`
The log level to use (debug, info, log, warn, error, none). Defaults to `log`.
### Set config filename `--config` or `-c`
The name of the config file, found where the command is run from. Defaults to `trigger.config.ts`.
### Set the projectRef `--project-ref` or `-p`
The project ref. Required if there is no config file.
### Self-hosted options
These options are usually only relevant to self-hosters or for local development.
#### Skip deploying the image `--skip-deploy` or `-D`
Load the built image into your local docker.
#### Self-hosted (builds locally) `--self-hosted`
Builds and loads the image using your local docker. Use the `--registry` option to specify the registry to push the image to when using `--self-hosted`, or just use `--push` to push to the default registry.
#### Registry `--registry`
<ComingSoon />
The registry to push the image to when using --self-hosted.
#### Push image `--push`
When using the --self-hosted flag, push the image to the default registry. (defaults to false when not using --registry)
#### Tag the image `--tag`
<ComingSoon />
Specify the tag to use when pushing the image to the registry.
<CliDeployCommands/>
{/* todo add options, remove the reference docs */}
docs/cli-dev-commands.mdx
+9
View File
@@ -0,0 +1,9 @@
---
title: "CLI dev command"
sidebarTitle: "Dev"
description: "The `trigger.dev dev` command is used to run your tasks locally."
---
import CliDevCommands from "/snippets/cli-commands-develop.mdx";
<CliDevCommands />
docs/cli-dev.mdx
+2 -63
View File
@@ -3,67 +3,6 @@ title: "CLI dev command"
description: "The `trigger.dev dev` command is used to run your tasks locally."
---
This runs a server on your machine that can execute Trigger.dev tasks:
import CliDevCommands from "/snippets/cli-commands-develop.mdx";
<CodeGroup>
```bash npm
npx trigger.dev@beta dev
```
```bash pnpm
pnpm dlx trigger.dev@beta dev
```
```bash yarn
yarn dlx trigger.dev@beta dev
```
</CodeGroup>
It will first perform an update check to prevent version mismatches, failed deploys, and other errors. You will always be prompted first.
You will see in the terminal that the server is running and listening for requests. When you run a task, you will see it in the terminal along with a link to view it in the dashboard.
It is worth noting that each task runs in a separate Node process. This means that if you have a long-running task, it will not block other tasks from running.
## Options
### Attaching a local debugger
You can use the `--debugger` flag to run the server in debug mode. This will allow you to attach a debugger to the server and debug your tasks.
<CodeGroup>
```bash npm
npx trigger.dev@beta dev --debugger
```
```bash pnpm
pnpm dlx trigger.dev@beta dev --debugger
```
```bash yarn
yarn dlx trigger.dev@beta dev --debugger
```
</CodeGroup>
### Concurrently running the terminal
Install the concurrently package as a dev dependency:
```ts
concurrently --raw --kill-others npm:dev:remix npm:dev:trigger
```
Then add something like this in your package.json scripts. This assumes you're running Next.js so swap that bit out if you're not:
```json
"scripts": {
"dev": "concurrently --raw --kill-others npm:dev:*",
"dev:next": "next dev",
"dev:trigger": "npx trigger.dev@beta dev",
//...
}
```
<CliDevCommands />
docs/cli-development-commands.mdx
+9
View File
@@ -0,0 +1,9 @@
---
title: "CLI development commands"
sidebarTitle: "Development commands"
description: "Use these commands to help develop your tasks locally."
---
import CliDevelopCommands from '/snippets/cli-commands-develop.mdx';
<CliDevelopCommands/>
docs/cli-init-commands.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: "CLI init command"
sidebarTitle: "Init"
description: "Use these options when running the CLI `init` command."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta init
```
```bash pnpm
pnpm dlx trigger.dev@beta init
```
```bash yarn
yarn dlx trigger.dev@beta init
```
</CodeGroup>
## Options
<ParamField body="Project ref" type="--project-ref | -p">
The project ref to use when initializing the project.
</ParamField>
<ParamField body="Package tag" type="--tag | -t">
The version of the `@trigger.dev/sdk` package to install. Defaults to `3.0.0-beta.56`.
</ParamField>
<ParamField body="Skip package install" type="--skip-package-install">
Skip installing the `@trigger.dev/sdk` package.
</ParamField>
<ParamField body="Override config" type="--override-config">
Override the existing config file if it exists.
</ParamField>
<ParamField body="Package arguments" type="--pkg-args">
Additional arguments to pass to the package manager. Accepts CSV for multiple args.
</ParamField>
<ParamField body="Login profile" type="--profile">
The login profile to use. Defaults to "default".
</ParamField>
<ParamField body="API URL" type="--api-url | -a">
Override the default API URL. If not specified, it uses `https://api.trigger.dev`.
</ParamField>
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to "log".
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/cli-introduction.mdx
+27
View File
@@ -0,0 +1,27 @@
---
title: "Introduction"
description: "The Trigger.dev CLI has a number of options and commands to help you develop locally, self host, and deploy your tasks."
---
## Standard options
<ParamField body="Help" type="--help | -h">
Displays a list of all help commands.
</ParamField>
<ParamField body="Version" type="--version | -v">
Displays the version number.
</ParamField>
## Commands
| Command | Description |
| :------------------------------------------------------- | :--------------------------------------------------------------------- |
| [Login](/cli-login-commands) | Login with Trigger.dev so you can perform authenticated actions. |
| [Init](/cli-init-commands) | Initialize your existing project for development with Trigger.dev. |
| [Dev](/cli-dev-commands) | Run your Trigger.dev tasks locally. |
| [Deploy](/cli-deploy-commands) | Deploy your Trigger.dev v3 project to the cloud. |
| [Whoami](/cli-whoami-commands) | Display the current logged in user and project details. |
| [Logout](/cli-logout-commands) | Logout of Trigger.dev. |
| [List-profiles](/cli-list-profiles-commands) | List all of your CLI profiles. |
| [Update](/cli-update-commands) | Updates all `@trigger.dev/*` packages to match the CLI version. |
docs/cli-list-profiles-commands.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: "CLI list profiles command"
sidebarTitle: "List profiles"
description: "Use these options when using the `list-profiles` CLI command."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta list-profiles
```
```bash pnpm
pnpm dlx trigger.dev@beta list-profiles
```
```bash yarn
yarn dlx trigger.dev@beta list-profiles
```
</CodeGroup>
## Options
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/cli-login-commands.mdx
+51
View File
@@ -0,0 +1,51 @@
---
title: "CLI login command"
sidebarTitle: "Login"
description: "Use these options when logging in to Trigger.dev using the CLI."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta login
```
```bash pnpm
pnpm dlx trigger.dev@beta login
```
```bash yarn
yarn dlx trigger.dev@beta login
```
</CodeGroup>
## Options
<ParamField body="Login profile" type="--profile">
Specifies the login profile to use. If not provided, it defaults to "default".
</ParamField>
<ParamField body="API URL" type="-a | --api-url">
Overrides the default API URL. If not specified, it uses `https://api.trigger.dev`.
</ParamField>
<ParamField body="Log level" type="-l | --log-level">
Sets the CLI log level. Available options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This setting doesn't affect the log level of your trigger.dev tasks. The default is `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opts out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Version" type="--version | -v">
Displays the version number of the CLI.
</ParamField>
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/cli-logout-commands.mdx
+48
View File
@@ -0,0 +1,48 @@
---
title: "CLI logout command"
sidebarTitle: "Logout"
description: "Use these options when using the `logout` CLI command."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta logout
```
```bash pnpm
pnpm dlx trigger.dev@beta logout
```
```bash yarn
yarn dlx trigger.dev@beta logout
```
</CodeGroup>
## Options
<ParamField body="Login profile" type="--profile">
The login profile to use. Defaults to `default`.
</ParamField>
<ParamField body="API URL" type="--api-url | -a">
Override the API URL. Defaults to `https://api.trigger.dev`.
</ParamField>
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/cli-update-commands.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: "CLI update command"
sidebarTitle: "Update"
description: "Use these options when using the `update` CLI command."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta update
```
```bash pnpm
pnpm dlx trigger.dev@beta update
```
```bash yarn
yarn dlx trigger.dev@beta update
```
</CodeGroup>
## Options
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/cli-whoami-commands.mdx
+48
View File
@@ -0,0 +1,48 @@
---
title: "CLI whoami command"
sidebarTitle: "Whoami"
description: "Use these options to display the current logged in user and project details."
---
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta whoami
```
```bash pnpm
pnpm dlx trigger.dev@beta whoami
```
```bash yarn
yarn dlx trigger.dev@beta whoami
```
</CodeGroup>
## Options
<ParamField body="Login profile" type="--profile">
The login profile to use. Defaults to `default`.
</ParamField>
<ParamField body="API URL" type="--api-url | -a">
Override the API URL. Defaults to `https://api.trigger.dev`.
</ParamField>
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
docs/mint.json
+19
View File
@@ -182,6 +182,25 @@
}
]
},
{
"group": "CLI",
"pages": [
"cli-introduction",
{
"group": "Commands",
"pages": [
"cli-login-commands",
"cli-init-commands",
"cli-dev-commands",
"cli-deploy-commands",
"cli-whoami-commands",
"cli-logout-commands",
"cli-list-profiles-commands",
"cli-update-commands"
]
}
]
},
{
"group": "Open source",
"pages": ["open-source-self-hosting", "open-source-contributing", "github-repo"]
docs/snippets/cli-commands-deploy.mdx
+84
View File
@@ -0,0 +1,84 @@
Run the command like this:
<CodeGroup>
```bash npm
npx trigger.dev@beta deploy
```
```bash pnpm
pnpm dlx trigger.dev@beta deploy
```
```bash yarn
yarn dlx trigger.dev@beta deploy
```
</CodeGroup>
<Warning>This will fail in CI if any version mismatches are detected. Ensure everything runs locally first using the [dev](/cli-dev) command and don't bypass the version checks!</Warning>
It performs a few steps to deploy:
1. Optionally updates packages when running locally.
2. Typechecks the code.
3. Compiles and bundles the code.
4. Checks that [environment variables](/deploy-environment-variables) are set.
5. Deploys the code to the cloud.
6. Registers the tasks as a new version in the environment (prod by default).
You can also setup [GitHub Actions](/github-actions) to deploy your tasks automatically.
## Options
<ParamField body="Environment" type="--env | -e">
Defaults to `prod` but you can specify `staging`.
</ParamField>
<ParamField body="Skip typecheck" type="--skip-typecheck">
Skips the pre-build typecheck step.
</ParamField>
<ParamField body="Skip update check" type="--skip-update-check">
Skip checking for `@trigger.dev` package updates.
</ParamField>
<ParamField body="Build platform" type="--build-platform">
The platform to build the deployment image for. Defaults to `linux/amd64`.
</ParamField>
<ParamField body="Log level" type="--log-level | -l">
The log level to use (debug, info, log, warn, error, none). Defaults to `log`.
</ParamField>
<ParamField body="Set config filename" type="--config | -c">
The name of the config file, found where the command is run from. Defaults to `trigger.config.ts`.
</ParamField>
<ParamField body="Set the projectRef" type="--project-ref | -p">
The project ref. Required if there is no config file.
</ParamField>
## Self-hosting
These options are typically used when [self-hosting](/open-source-self-hosting) or for local development.
<ParamField body="Skip deploying the image" type="--skip-deploy | -D">
Load the built image into your local docker.
</ParamField>
<ParamField body="Self-hosted (builds locally)" type="--self-hosted">
Builds and loads the image using your local docker. Use the `--registry` option to specify the registry to push the image to when using `--self-hosted`, or just use `--push` to push to the default registry.
</ParamField>
<ParamField body="Registry" type="--registry">
**This option is coming soon.** The registry to push the image to when using --self-hosted.
</ParamField>
<ParamField body="Push image" type="--push">
When using the --self-hosted flag, push the image to the default registry. (defaults to false when not using --registry)
</ParamField>
<ParamField body="Tag the image" type="--tag">
**This option is coming soon.** Specify the tag to use when pushing the image to the registry.
</ParamField>
docs/snippets/cli-commands-develop.mdx
+102
View File
@@ -0,0 +1,102 @@
This runs a server on your machine that can execute Trigger.dev tasks:
<CodeGroup>
```bash npm
npx trigger.dev@beta dev
```
```bash pnpm
pnpm dlx trigger.dev@beta dev
```
```bash yarn
yarn dlx trigger.dev@beta dev
```
</CodeGroup>
It will first perform an update check to prevent version mismatches, failed deploys, and other errors. You will always be prompted first.
You will see in the terminal that the server is running and listening for requests. When you run a task, you will see it in the terminal along with a link to view it in the dashboard.
It is worth noting that each task runs in a separate Node process. This means that if you have a long-running task, it will not block other tasks from running.
## Options
<ParamField body="Config file" type="--config | -c">
The name of the config file, found at [path].
</ParamField>
<ParamField body="Project ref" type="--project-ref | -p">
The project ref. Required if there is no config file.
</ParamField>
<ParamField body="Debugger" type="--debugger">
You can use this flag to run the server in debug mode. This will allow you to attach a debugger to the server and debug your tasks.
<CodeGroup>
```bash npm
npx trigger.dev@beta dev --debugger
```
```bash pnpm
pnpm dlx trigger.dev@beta dev --debugger
```
```bash yarn
yarn dlx trigger.dev@beta dev --debugger
```
</CodeGroup>
</ParamField>
<ParamField body="Debug OpenTelemetry" type="--debug-otel">
Enable OpenTelemetry debugging.
</ParamField>
<ParamField body="Skip update check" type="--skip-update-check">
Skip checking for `@trigger.dev` package updates.
</ParamField>
<ParamField body="Login profile" type="--profile">
The login profile to use. Defaults to `default`.
</ParamField>
<ParamField body="API URL" type="--api-url | -a">
Override the API URL. Defaults to `https://api.trigger.dev`.
</ParamField>
<ParamField body="Log level" type="--log-level | -l">
The CLI log level to use. Options are `debug`, `info`, `log`, `warn`, `error`, and `none`. This does not affect the log level of your trigger.dev tasks. Defaults to `log`.
</ParamField>
<ParamField body="Skip telemetry" type="--skip-telemetry">
Opt-out of sending telemetry data.
</ParamField>
## Standard options
<ParamField body="Help" type="--help | -h">
Shows the help information for the command.
</ParamField>
## Concurrently running the terminal
Install the concurrently package as a dev dependency:
```ts
concurrently --raw --kill-others npm:dev:remix npm:dev:trigger
```
Then add something like this in your package.json scripts. This assumes you're running Next.js so swap that bit out if you're not:
```json
"scripts": {
"dev": "concurrently --raw --kill-others npm:dev:*",
"dev:next": "next dev",
"dev:trigger": "npx trigger.dev@beta dev",
//...
}
```
docs/triggering.mdx
+1 -1
View File
@@ -9,7 +9,7 @@ Trigger tasks **from your backend**:
| -------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tasks.trigger()` | Anywhere | Triggers a task and gets a handle you can use to fetch and manage the run. [Read more](#tasks-trigger) |
| `tasks.batchTrigger()` | Anywhere | Triggers a task multiple times and gets a handle you can use to fetch and manage the runs. [Read more](#tasks-batchtrigger) |
| `tasks.triggerAndPoll()` | Anywhere | Triggers a task and then polls the run until it’s complete. [Read more](#tasks-triggerandpoll) |
| `tasks.triggerAndPoll()` | Anywhere | Triggers a task and then polls the run until it’s complete. [Read more](#tasks-triggerandpoll) |
Trigger tasks **from inside a run**:
docs/versioning.mdx
+1 -3
View File
@@ -49,8 +49,6 @@ Every deployment creates a new version of all tasks for that environment.
When a task has an uncaught error it will [retry](/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.
If all the attempts have failed you can start a [reattempt](/reattempting-replaying). This will be version locked to the original version of the run.
## Replays
A "replay" is a new run of a task that uses the same inputs but will use the latest version of the code. This is useful when you fix a bug and want to re-run a task with the same inputs. See [replays](/reattempting-replaying) for more information.
A "replay" is a new run of a task that uses the same inputs but will use the latest version of the code. This is useful when you fix a bug and want to re-run a task with the same inputs. See [replaying](/replaying) for more information.
docs/writing-tasks-introduction.mdx
+1 -1
View File
@@ -9,7 +9,7 @@ Before digging deeper into the details of writing tasks, you should read the [fu
## Writing tasks
| Topic | Description |
| ----------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------- |
| :---------------------------------------------------| :------------------------------------------------------------------------------------------------------------------------ |
| [Logging](/logging) | View and send logs and traces from your tasks. |
| [Errors & retrying](/errors-retrying) | How to deal with errors and write reliable tasks. |
| [Wait](/wait) | Wait for periods of time or for external events to occur before continuing. |