Which commands create tasks
Not every command starts a task, and the ones that do differ in whether they wait for it.pin and unpin hold or release a release version without deploying. See Holding a release.
create, replace, update, and delete do not accept --reason, --no-watch, --timeout, or --poll-interval. To follow what they started, look up the task as described in the next section.
Find a task
List the latest tasks for one installation, or for every installation in an environment:INSTALLATION column. --limit caps the number of tasks returned. -e is required. The aliases installation-tasks and task also work.
The table has the columns STATUS, TASK TYPE, ROLLOUT, ENV CONFIG, AGE, DESCRIPTION, and TASK ID. A status carries a suffix when it matters:
If you pass a task UUID instead of an installation name, the command shows that task, like
ryvn task get.
An environment’s infrastructure tasks, such as provisioning plans, appear under Infrastructure in the environment description:
Approve: and Retry: lines appear only while the task can be approved or retried. ryvn get environment also shows Plan Awaiting Approval, Planning, or Plan Failed in its status column when a plan decides what happens next.
Inspect a task
Three commands show different parts of a task.describe installation-taskis the first stop for a failed task. It prints the failure reason and the task log.task getshows deployment settings, workload counts, resources still waiting to become ready, and pod details when available. The states reflect the task’s last update, not the installation’s current health.task outputprints the Terraform plan, Pulumi preview, Helm diff, or artifact sync report for a task, including the result of adry-run. If a task has no output, the command saysNo resource changes in task output.
-o json.
Review a plan, then approve
When an environment or service requires approval, a task stops after it produces a plan or diff and waits. The plan can be a Terraform plan, a Pulumi preview, or a Helm diff. Deployment approvals explains what decides whether a task waits.1
Find the task
Use
ryvn get installation-task my-app -e production, or the Task ID under Infrastructure in ryvn describe environment. A command that watches also prints the ID in its first line, unless you passed --no-watch.2
Read the plan
3
Approve, cancel, or retry
cancelstops a task that is running or pending. A finished plan that is waiting for approval can’t be cancelled. To keep it from applying, don’t approve it.retryre-runs a task that failed. If the cause was a bad config or version, fix that first, because a retry repeats the same task.- Each of the three also accepts
-o json, which prints{"taskId": "...", "status": "accepted"}. The commands printApproval requested,Task cancelled, orTask retried. Approval is asynchronous, so these confirm the request, not the result. Check the task afterwards. - A Pulumi approval authorizes the previewed operation, not identical changes. Pulumi recalculates the changes when execution starts.
The --reason flag
--reason is optional. On task approve, cancel, and retry it stays empty when you omit it. It also works on ryvn command operations, except sync-artifacts, which rejects it. When you omit it there, the CLI fills it in with cli preview (commit sha: <sha>), or cli preview (uuid: <id>) when it cannot read a commit SHA. redeploy uses cli redeploy in place of cli preview.
task approve, cancel, and retry take only a task ID. The CLI finds the installation by searching your environments’ recent activity. If the task does not appear there, the command fails with task <id> not found in any environment's recent activity.
Watch a command
Task-creatingryvn command operations poll until the task ends. They print Watching task <id> for installation '<name>'..., each status change, the task log, and a final summary. Statuses that end the watch are COMPLETED, FAILED, and CANCELLED. A failed or cancelled task makes the command exit with an error. When the task is approvable or retryable, the summary prints the ryvn task approve or ryvn task retry command to use next.
ryvn command dry-run runs a Helm diff or Terraform plan without applying it. Add --disable-approvals to create a preview that cannot be applied.
If a watch ends with timeout after <duration>, the task is still running. Check the existing task with ryvn get installation-task or ryvn task get <task-id>. Don’t rerun the original command to keep watching: that submits the operation again, which can run a job twice. Choose a longer --timeout before you start the operation.
If the CLI cannot find the task it just created, it fails with no task found in recent activity after 3 attempts. For redeploy, this can mean deployment constraints blocked the task, such as an unmet dependency or an installation that is waiting for a platform blueprint upgrade. Check ryvn get installation <name> -e <env>.
Choose between redeploy, update, and retry
redeploy deploys the installation’s current config and the latest release from its release channel. It changes no configuration.
Delete installations and environments
Deletion starts teardown immediately. Neither command asks for confirmation.Installation "my-app" delete request accepted and the commands to check progress. Teardown runs as a task, and where approval is required that task waits like any other. When you delete several installations at once, the command exits with an error if any of them failed, and -o json reports each result. Besides names, delete installation accepts --id (repeatable) and -f with a ServiceInstallation file.
A deletion request stays open until its destroy task starts. While one is open, ryvn describe installation my-app -e production shows Deletion: open (<deletion-id>). To inspect or cancel it:
cannot deprovision environment "staging" when Terraform installations remain or deletion protection is on, so delete the installations first. On success you see either Environment "staging" deleted (the environment was never provisioned) or Environment "staging" is being deprovisioned. It will be deleted once deprovisioning completes.
Debug a failed deployment
Work from the cheapest, most specific evidence to the most expensive. Stop when you find the cause.1
Read the installation's state
Deploy, Health, and any open Deletion. Add -o json for the full record.2
Read the failing task
[APPROVABLE] has not failed. It is waiting for ryvn task approve.3
Look at what the task planned
4
Check the Kubernetes objects
describe manifest works like kubectl describe. It shows metadata, owner references, status, spec, and events. Name a resource as TYPE, TYPE NAME_PREFIX, or TYPE/NAME. All three commands accept -o json.5
Read the logs
6
Run kubectl against the cluster
ryvn metrics network my-app -e production shows requests, errors, and latency. See Network metrics.
Common causes
Provision and approve an environment
Creating an environment, or changing its config or platform inputs, plans the infrastructure change:ryvn update environment requires a patch. Running it with none is an error.
If the CLI prints Created a plan for environment "staging"; provisioning starts once it is approved, review and approve the plan it names:
Provisioning started for environment "staging", the environment is already applying and needs no approval. Installations cannot deploy until provisioning completes. Follow it with:
Run provisioning from your own infrastructure
For an environment provisioned by an external executor, two one-shot commands run a single pending task and exit:provision) or destroy (deprovision) task for that environment, claims it, runs it, and exits. When no task is pending, it logs No pending provision tasks found or No pending deprovision tasks found and exits without error. A task already claimed by another worker fails with task <id> already claimed by another worker. The commands authenticate with the credentials in ~/.ryvn/credentials.yaml, or with a service user’s --client-id and --client-secret.
These commands apply or destroy real infrastructure, and
deprovision tears down the environment’s cloud resources. Run them only when you operate the executor for that environment.