CLI Deploy
Learn how the jamdesk deploy CLI command packages, uploads, and builds your docs, including flags, build phases, and error codes.
The deploy command packages your docs, uploads them to Jamdesk, and triggers a build from the terminal. Use it for quick iterations, testing changes, or projects not connected to a GitHub repo.
Quick Start
jamdesk login # First time only
jamdesk deploy # From your project directoryOptions
| Flag | Description |
|---|---|
--detach | Queue the build and exit immediately (prints a dashboard link) |
--full-rebuild | Force a full rebuild, bypassing the build cache |
--project <id> | Deploy to a specific project ID (skips interactive selection) |
--allow-empty | Allow deploying with zero .mdx content pages. By default the CLI refuses to deploy an empty project. This stops a wrong working directory from publishing an empty site. Snippets don't count as content pages |
jamdesk push is an alias for jamdesk deploy.
How It Works
Verifies your session. An expired token prompts you to run jamdesk login.
Reads and validates docs.json from the current directory.
Reads projectId from docs.json. It's missing on the first deploy. The CLI then prompts you to pick a project. The CLI saves your choice to docs.json. The next deploy skips the prompt.
Use --project <id> to override.
Creates a compressed tarball of your docs. Files in .gitignore are left out. The CLI warns about files that look like secrets. The warning doesn't block the upload.
Sends the tarball to Jamdesk via a presigned URL. Maximum upload size is 100 MB.
Queues a build and polls for status. Each phase prints as it completes. Press Ctrl+C to stop polling. The build continues in the background.
Prints the live URL when the build finishes.
Build Phases
The CLI prints each phase in order while it polls:
| Phase | Description |
|---|---|
| Extracting files | Unpacking the uploaded tarball |
| Validating configuration | Checking docs.json schema and content |
| Preparing content | Processing MDX files and assets |
| Building documentation | Compiling pages and generating static artifacts |
| Uploading to CDN | Pushing built output to the edge network |
| Refreshing cache | Purging stale content from the CDN |
File Exclusions
These are always excluded from uploads, whatever your .gitignore says:
.git, node_modules, .next, .env, .env.*, *.pem, *.key, credentials.json, .gcloud, .DS_Store, Thumbs.db
Everything in your .gitignore is also excluded.
Secret file warnings
The CLI warns (but doesn't block) when it detects files that look like secrets:
.envand.env.*files*.pemand*.keyfilescredentials.jsonservice_account*.json- Files starting with
secret
Add them to .gitignore to suppress the warning and exclude them from uploads.
Error Reference
| Error | Code | Cause | Fix |
|---|---|---|---|
| Not logged in | AUTH_REQUIRED | No stored credentials | jamdesk login |
| Session expired | AUTH_EXPIRED | Token refresh failed | jamdesk login |
| Access denied | FORBIDDEN | Not a member of this project | Check project membership in dashboard |
| Project not found | NOT_FOUND | Invalid project ID | Verify ID or remove projectId from docs.json |
| Build in progress | BUILD_IN_PROGRESS | Another build is running | Wait or check dashboard |
| Upload too large | TOO_LARGE | Server rejected upload (100 MB limit) | Exclude large files via .gitignore |
| Project too large | PROJECT_TOO_LARGE | Tarball exceeds 100 MB during packaging | Exclude large files via .gitignore |
| No projects | NO_PROJECTS | No projects in your account | Create a project in the dashboard first |
| No files | EMPTY_PROJECT | All files excluded | Check .gitignore |
| No content pages | NO_CONTENT | Zero .mdx content pages found (snippets don't count) | Run from your docs directory, or pass --allow-empty if the empty publish is intentional |
| Config invalid | CONFIG_NOT_FOUND | Missing or invalid docs.json | Run from project root, check config |
| Upload failed | UPLOAD_FAILED | Network issue during upload | Check internet, retry |
| Build failed | BUILD_FAILED | Build service error | Check build logs in dashboard |
Troubleshooting
Each project runs one build at a time. Wait for the current build to finish. Check status in the dashboard under Deployments.
Run the command from the directory that contains docs.json. Run jamdesk validate to check for config errors.
The 100 MB limit applies to the compressed tarball of every file not excluded. Large images, videos, or data files are common causes. Add them to .gitignore to exclude them.
Press Ctrl+C to exit. The build keeps running in the background. Check the dashboard for status. A hang that keeps coming back can mean your network drops the polling requests.
You need at least one project in your Jamdesk account. Create one at dashboard.jamdesk.com.
For more CLI troubleshooting, see the Help Center CLI guide.