Skip to main content
troqcloud An application in troqcloud is the central unit of work on the platform. When you run troq ship, the platform creates or updates an application record, builds your source code into a container image, places that image on a managed node in the fleet, starts the container, and wires a public hostname to it through the proxy layer. The troq apps command group gives you full operator control over that application after it exists: inspect its state, manage its lifecycle, walk its release history, and permanently decommission it when it is no longer needed. Every troq apps command reads the active app from the troq.toml file in your current working directory. This is not a session setting. There is no global “current app” stored anywhere. Each time you run a command, the CLI reads troq.toml from the directory you are in at that moment. If no troq.toml is found and no --app-id flag is passed, the CLI prompts you with an interactive fuzzy selector listing all apps in the workspace. This means switching between apps is as simple as switching directories, with no explicit context management required.

Listing Applications

troq apps list returns all applications in the active workspace, showing the app ID, display name, public hostname, status, and creation date.
The list is paginated. Use --limit and --offset to walk through large workspaces:
The status field reflects the current lifecycle state of each application. The possible values are active, suspended, and destroyed. Applications that have been destroyed will not appear in this list, as soft deletion removes them from the standard query path.

Inspecting an Application

troq apps show returns the full application record for a single app: its ID, name, hostname, region, lifecycle status, source configuration, and timestamps.
troq apps status returns the runtime status specifically, showing what state the platform considers the application to be in at the current moment. This is the right command to run when you want a quick health check without the full record detail.
The two commands cover different concerns. show gives you the configuration record as stored. status gives you the current operational state. When something looks wrong with a running app, check status first.

App Context and Directory Convention

troqcloud’s CLI follows a directory-per-app convention. Your app’s source directory contains a troq.toml file that records the workspace and app ID. Every CLI command reads this file from the current directory at runtime. There is no session-level context to manage and no need to switch apps with a separate command. The practical workflow is:
If you run a command from a directory that has no troq.toml, the CLI resolves the app interactively using a fuzzy selector. If you are in a CI/CD environment or a script where there is no terminal, pass --app-id explicitly:

Suspending an Application

troq apps suspend stops the running application container on the fleet node and marks the application as suspended in the platform. Suspension is reversible, a suspended app retains all its data, secrets, configuration, and release history. It is simply not running.
What happens when you suspend:
  1. The platform transitions the application’s status from active to suspended in the database.
  2. A control event is published to the deployer, which forwards it to the node agent running on the VM hosting your app.
  3. The node agent sends SIGTERM to the application container and waits for it to exit cleanly.
  4. The container stops. The public hostname remains configured in the proxy, but traffic will not reach an upstream until the app is resumed.
Suspension is the right operation before any of the following: taking the app offline temporarily for maintenance, rolling back a bad deploy manually, or permanently removing the app. The destroy command requires the app to be suspended first.

Resuming a Suspended Application

troq apps resume brings a suspended application back online. It reverses the suspension: the platform transitions the status from suspended to active, publishes a resume event to the deployer, and the node agent restarts the container from the image that was running when suspension happened.
No new build is triggered by resume. The container that was stopped is the container that restarts. If you want to resume with new code or new secrets, run troq ship instead, which triggers a full build and deploy cycle and brings the app back to active with the new release. Resume is only valid from the suspended state. If you attempt to resume an active application, the server returns a 409 with an invalid state transition error.

Destroying an Application

troq apps destroy permanently removes an application from the platform. This is not reversible. The application record is soft-deleted, its proxy routes are decommissioned, and the deployer tears down the workload on the fleet node, removing the container entirely rather than just stopping it. Before you can destroy an app, it must be suspended. Attempting to destroy an active application returns an error:
The required sequence is:
--yes is required as a global flag before apps to bypass the interactive confirmation prompt. In interactive mode the CLI will ask for confirmation before proceeding. Do not skip this step in scripts, destruction is permanent. What happens when you destroy:
  1. The CLI checks the app’s current status. If it is not suspended, the command is rejected locally before any request is sent.
  2. The platform soft-deletes the application record in the database.
  3. A decommission event is published to the deployer, which removes the workload from the fleet node, stopping and deleting the container.
  4. A route decommission event is published to the proxy layer, which removes the hostname-to-upstream mapping from the Caddy configuration. The hostname stops responding to traffic immediately.
After destruction, the app no longer appears in troq apps list, its releases are no longer queryable, and its secrets are soft-deleted. There is no undo. If you need the app again, you must create a new one and redeploy from source.

Releases

Every successful deployment creates a release. A release records the container image fingerprint, the deployment outcome, the environment, the revision number, and the timestamp of when it succeeded. Releases are the platform’s record of what has run on your app and when.

Listing Releases

troq apps releases-list returns all releases for an application in reverse chronological order.
Each release shows its ID, revision number, deployment state, release state, environment, and the Unix timestamp of when it completed. The revision number is a monotonically incrementing integer: revision 1 is the first successful deploy, revision 2 is the second, and so on.

Showing a Specific Release

troq apps release-show returns the full detail record for a single release. When run interactively, the CLI fetches the release list and presents a fuzzy selector so you can pick the release by ID and revision:
In non-interactive mode or scripts, pass --release-id directly:
The fuzzy selector displays each release as <release_id> rev=<N> <state>, with the most recent release at the top. This makes it easy to identify and inspect any point in your deployment history without copying release IDs manually.

Latest Release

troq apps release-latest returns the most recent release without having to scroll through the full list. This is the right command when you want to confirm what is currently deployed.

Non-Interactive and Automation Usage

All troq apps commands work without prompts when the required values are supplied as flags. This is the expected pattern for CI/CD pipelines, deployment scripts, and LLM-driven tooling.
The --app-id flag always takes precedence over troq.toml. The --workspace global flag overrides the workspace when it is not already resolved from profile or project context. For lifecycle operations in automation, always pass --yes before the apps subcommand to suppress confirmation prompts:

Output Formats

All apps commands support --output table, --output json, and --output jsonl. Table is the default. JSON and JSONL carry the full response payload and are suitable for piping into downstream tools.

Permission Requirements

Read operations (list, show, status, releases-list, release-show, release-latest) require apps.read. Lifecycle and write operations (suspend, resume, destroy) require deploy.write. You can verify your access with:
If access is missing, ask your workspace owner to assign a role that carries the required permission. Use troq rbac roles-permissions-list to see what each role grants before requesting a change. Last Updated: 2026-05-11