Deploy and run
Buckets, queues and secrets
Store files in buckets, pass work between services with queues, keep secrets in step with your vault, rotate them, and ship logs elsewhere.
Besides apps and databases, a project can store files in buckets, pass background work through queues, keep secrets in step with Doppler or Vault, rotate passwords on a schedule, and send logs to other tools.
How to do it: in a project, press Add for a bucket or a queue: CLI connects it to your app with variables, so there's nothing extra to install. Secret sync, rotation and log drains are in project settings.
"Add a bucket for user uploads and connect it to my web app."
Beyond apps and databases, CLI gives your project object storage for files, durable queues for background work, and tools that look after secrets for you. Each one connects to your app through variables, so there are no extra SDKs to install.
Buckets
A bucket stores files: user uploads, generated reports, images. Use a bucket rather than the container's disk, which is replaced on every deploy. Buckets are billed per GB stored each month.
Create a bucket and link it
Linking a bucket to a service gives it two variables: BUCKET_URL and BUCKET_TOKEN. Redeploy the service so it sees them.
In the dashboard: open the project's Settings and find Buckets.
From your terminal:
cli bucket create uploads
cli bucketsThe linked service gets the variables. Add --public to let anyone read files without a token.
Ask your agent:
"Add a bucket called uploads for web, so users can upload avatars."
With the API:
POST /v1/projects/:id/buckets{ "name": "uploads", "link": { "serviceId": "svc_web123" } }Use it from your app
Your app reads and writes files with plain HTTP requests, sending the token:
PUT $BUCKET_URL/avatars/42.png
GET $BUCKET_URL/avatars/42.png
DELETE $BUCKET_URL/avatars/42.png
GET $BUCKET_URL?prefix=avatars/
Authorization: Bearer $BUCKET_TOKENThe body is the raw file, up to 100 MB. The last request lists files under a prefix.
Signed links for browsers
To let a browser download or upload one file directly, make a link that expires. It can last from 1 minute to 7 days.
From your terminal:
cli bucket put uploads ./report.pdf reports/october.pdf
cli bucket url uploads reports/october.pdf --days 2With the API:
POST /v1/buckets/:id/sign{ "key": "reports/october.pdf", "method": "GET", "seconds": 3600 }method is GET to download or PUT to upload.
Queues
A queue holds messages for background work: one service sends jobs, another works through them. Messages are kept until a worker confirms it handled them. Queues are billed per operation.
Create a queue
Link the queue to every service that sends or receives. Each gets QUEUE_URL and QUEUE_TOKEN.
In the dashboard: open the project's Settings and find Queues.
From your terminal:
cli queue create emails
cli queuesWith the API:
POST /v1/projects/:id/queues{ "name": "emails", "link": { "serviceIds": ["svc_web123", "svc_worker456"] }, "maxAttempts": 5, "visibilitySeconds": 30 }Send messages
Producers post a JSON body, with Authorization: Bearer $QUEUE_TOKEN:
POST $QUEUE_URL/messages{ "body": { "to": "[email protected]", "template": "welcome" } }You can send up to 100 at once as {"messages": [...]}, and delay a message with delaySeconds.
Work through them
Workers ask for messages, handle them, then acknowledge them:
POST $QUEUE_URL/receivewith{"max": 10, "waitSeconds": 20}. WithwaitSeconds, the request waits up to 20 seconds for a message to arrive (long polling), instead of returning empty at once.- Handle each message.
POST $QUEUE_URL/ackwith{"receipts": [...]}from the messages you handled.
A message you don't acknowledge comes back after the visibility window (30 seconds by default), so another worker can try it. To hand one back sooner, use POST $QUEUE_URL/nack.
Dead letters
After maxAttempts tries (5 by default), a message moves to the queue's dead letters instead of coming back. GET $QUEUE_URL/dead lists them, and POST $QUEUE_URL/redrive puts them back in the queue once you've fixed the cause.
Push mode
Instead of running a worker that polls, CLI can push each message to a path on your app:
cli queue create emails --push /jobs/email{ "name": "emails", "push": { "serviceId": "svc_worker456", "path": "/jobs/email" } }Each push carries an X-CLI-Signature header, so your app can check it came from CLI.
Secret sync
Keep your variables in step with Doppler, HashiCorp Vault (KV v2), or any HTTPS endpoint that returns JSON. CLI pulls every 5 minutes and only changes the keys it wrote, so variables you set by hand are left alone. Syncs can fill one service's variables or the project's shared variables, and can redeploy when something changes. Setting one up needs an admin.
In the dashboard: open the project's Settings and find Secrets from your vault.
From your terminal:
cli secrets sync doppler dp.st.prd.xxxx
cli secrets sync doppler dp.st.prd.xxxx --shared --redeploy
cli secretsWith the API:
POST /v1/projects/:id/secret-syncs{ "provider": "vault", "token": "hvs.…", "url": "https://vault.example.com", "path": "secret/data/web", "serviceId": "svc_web123", "autoDeploy": true }Use "serviceId": null for shared variables. Each sync raises a secrets_synced event.
Secret rotation
CLI can replace a secret on a schedule, such as a session signing key every 30 days. When it rotates, the old value stays available as KEY_PREVIOUS (for example SESSION_SECRET_PREVIOUS) for a grace period, 24 hours by default, so sessions and tokens signed with the old value still verify. Have your app accept both during that time.
On a database, rotation changes the password in place and redeploys the apps that use it. There's no key to name.
From your terminal:
cli secrets rotate SESSION_SECRET --every 30
cli secrets rotate --service postgres --every 90The second command rotates the postgres database's password.
With the API:
POST /v1/services/:id/rotations
POST /v1/rotations/:id/rotate{ "key": "SESSION_SECRET", "everyDays": 30, "graceHours": 24 }The second endpoint rotates now. Each rotation raises a secrets_rotated event.
Log drains
Send your services' output to Datadog, Axiom, Better Stack or any HTTPS endpoint. Secret values are masked before anything leaves CLI. A drain covers every running service in the project unless you pick some.
In the dashboard: open the project's Settings and find Log drains. Each drain has a button to send a test line.
With the API:
POST /v1/projects/:id/drains
POST /v1/projects/:id/drains/:drain/test{ "target": { "kind": "datadog", "apiKey": "…" }, "services": ["svc_web123"] }kind is datadog (with apiKey), axiom (with a token and dataset), betterstack (with a token) or http (with a URL).
Next steps
- Variables and references: Variables and configuration.
- Logs, traces and errors inside CLI: Monitoring and logs.
- Roles and who can read secrets: Teams and security.