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 |
-m, --message <text> | Commit message for uncommitted changes in a folder made by jamdesk pull (default: "Update docs") |
--allow-secret-files | Publish files whose names look like secrets from a folder made by jamdesk pull |
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.
Projects without GitHub
For a project whose docs Jamdesk hosts (Docs Without GitHub), you run deploy inside the folder that jamdesk pull made. There, deploy skips the tarball steps above. Instead it:
- Checks your changes and refuses files it won't publish, such as
.githubfiles, secret-looking files, and files over 25 MB, before it commits anything. - Commits your uncommitted changes. Use
-mto set the message. - Uploads the new commits (up to 100 MB), which Jamdesk adds to your docs.
- Starts a build and shows each phase.
Deploy works from any subfolder and never changes docs.json. --full-rebuild and --allow-empty don't apply in this folder, and --project must name the folder's own project. Unlike the warning in a normal deploy, a secret-looking file stops the deploy unless you add --allow-secret-files.
If Jamdesk has changes you don't have yet, from the Editor or a teammate, deploy stops and keeps your commit. Run jamdesk pull, then jamdesk deploy again. See Edit on your computer for conflicts and the full list of refused files.
| Error | Code | Fix |
|---|---|---|
| Jamdesk has changes you don't have yet | HOSTED_STALE | jamdesk pull, then jamdesk deploy |
| Nothing was published | PUSH_REFUSED | Remove or fix the listed files, then deploy again |
| A merge or rebase is not finished | MERGE_IN_PROGRESS | Fix the conflicts and commit, or run git merge --abort |
| Folder is on the wrong branch | WRONG_BRANCH | git switch to the branch the message names |
| Couldn't commit your changes | COMMIT_FAILED | Run git commit in the folder to see why |
| Jamdesk couldn't confirm the publish | PUSH_UNCONFIRMED | jamdesk pull to check, then deploy again |
| Project isn't hosted by Jamdesk anymore | NOT_HOSTED | Push to your GitHub repository with the commands deploy prints |
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.