> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# holydocs status

Check deployment status and view recent deployment history for your project.

## 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:

```
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:

```
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
```

```
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:

```
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 ID
holydocs deploy

# Check build progress
holydocs 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](/cli/deploy) -- Deploy documentation and trigger a build
- [holydocs login](/cli/login) -- Authenticate before checking status
- [CLI Overview](/cli/overview) -- Global flags and environment variables