holydocs status

Usage

bash
holydocs status [options]

Displays the most recent deployments for your project, including their status, branch, commit, and timing. You can also inspect the details of a specific deployment by its ID.

Options

Option	Description	Default
--project <id>	Project ID to check	From local config
--deployment <id>	Show details for a specific deployment	None (shows list)

Examples

View Recent Deployments

bash
holydocs status

Output:

text
Recent Deployments  ● dep_a1b2 success  main  c7f3e2a (8.1s)  2 minutes ago  ● dep_c3d4 success  main  a1b2c3d (7.3s)  1 hour ago  ● dep_e5f6 failed   feat  d4e5f6g (2.1s)  3 hours ago  ● dep_g7h8 success  main  g7h8i9j (9.0s)  1 day ago

Status indicators:

Icon	Status	Description
Green	success	Deployment completed and is live
Red	failed	Build or deployment failed
Blue	building / deploying	Deployment is in progress
Yellow	Other	Queued or in an intermediate state

View a Specific Deployment

bash
holydocs status --deployment dep_a1b2c3d4

Output:

text
Deployment Details  ID:       dep_a1b2c3d4e5f6g7h8i9j0  Status:   success  Branch:   main  Commit:   c7f3e2a — Update authentication guide  Duration: 8.1s  Created:  4/10/2026, 3:45:22 PM  Finished: 4/10/2026, 3:45:30 PM

Check a Specific Project

bash
holydocs status --project proj_abc123

Overrides the project ID stored in your local config. Useful when managing multiple documentation projects.

Failed Deployment Details

bash
holydocs status --deployment dep_e5f6g7h8

text
Deployment Details  ID:       dep_e5f6g7h8i9j0k1l2m3n4  Status:   failed  Branch:   feat/new-api  Commit:   d4e5f6g — Add payment endpoints  Duration: 2.1s  Error:    Build failed: Invalid MDX syntax in api/payments.mdx at line 23  Created:  4/10/2026, 12:30:15 PM  Finished: 4/10/2026, 12:30:17 PM

Authentication

The status command requires authentication to access the HolyDocs API. Authenticate using any of these methods:

1. Run holydocs login before using status
2. Set the HOLYDOCS_API_KEY environment variable

bash
HOLYDOCS_API_KEY=hd_a1b2c3d4e5f67890a1b2c3d4e5f67890 holydocs status --project proj_abc123

Project Resolution

The project ID is resolved in this order:

1. --project flag (explicit)
2. HOLYDOCS_PROJECT
3. projectId in ~/.holydocs/config.json (set during login or onboarding)

If no project ID is available, the command exits with an error:

text
Error: No project specified. Use --project <id>.

After your first deployment, the project ID is automatically saved to your local config. You typically only need the --project flag when checking a different project than your default.

Deployment List

The command shows up to 10 recent deployments, sorted by creation time (newest first). Each entry includes:

Field	Description
ID	First 8 characters of the deployment ID
Status	Current state (success, failed, building, deploying, queued)
Branch	Git branch that was deployed
Commit	First 7 characters of the commit SHA
Duration	Build time (if completed)
Time	Relative timestamp (e.g., "2 minutes ago")

Deployment Detail Fields

When viewing a specific deployment with --deployment, all available fields are shown:

Field	Description
ID	Full deployment ID
Status	Current state with color coding
Branch	Git branch
Commit	Short SHA and commit message
Duration	Build time in seconds
Error	Error message (only for failed deployments)
Created	Timestamp when the deployment was initiated
Finished	Timestamp when the deployment completed

Monitoring Builds

After running holydocs deploy, use status to monitor the build progress:

bash
# Deploy and note the deployment IDholydocs deploy# Check build progressholydocs status --deployment dep_xyz789

By default, holydocs deploy waits for the build to complete before exiting. The status command is most useful when you deployed with --no-wait or want to check a deployment that was triggered from the dashboard or a Git push.

Error Handling

Error	Cause	Resolution
"No project specified"	No --project flag and no saved project ID	Provide --project or run holydocs login and deploy
"Failed to fetch deployments"	Network error or invalid API key	Check your connection and re-authenticate
"Deployment not found"	Invalid deployment ID	Verify the ID from a previous status listing

Related

• holydocs deploy -- Deploy documentation and trigger a build
• holydocs login -- Authenticate before checking status
• CLI Overview -- Global flags and environment variables