Track Generation Progress

Keep each generation in view so you can tell whether docsfy is still working, already finished, or needs intervention. When you can see the current stage in real time, it is much easier to decide whether to wait, inspect a specific run, or stop and retry.

Prerequisites

• Access to a running docsfy server.
• A signed-in dashboard session or a configured CLI profile with a working key.
• An active run, or a repository you are ready to generate. See Generate Documentation for details.

Quick Example

docsfy generate https://github.com/org/my-repo --watch

This starts a run and keeps the terminal attached to live progress. docsfy prints the project name, branch, status, and generation ID, then streams updates until the run becomes ready, error, or aborted.

Note: --watch only attaches when the server returns generating. If the command returns ready immediately, docsfy decided that variant was already current.

Step-by-Step

1. Start the run in watch mode.

docsfy generate https://github.com/org/my-repo --watch

Use this when you want one command to submit the job and follow it live in the terminal. See CLI Command Reference for details.

1. Keep the dashboard open while the run is active.

Open the dashboard and select the active run from the list. While the connection stays healthy, the page updates automatically and shows:

• the current status: Generating, Ready, Error, or Aborted
• elapsed time while the run is still active
• page count and progress percentage when a plan is available
• the generation ID for later lookup
• an activity log that advances as stages complete

Tip: Copy the generation ID early for long runs. You can use it later with docsfy status or docsfy abort without retyping the branch, provider, and model.

1. Read the stage names as they change.

The terminal watcher and dashboard activity log use these stage names:

1. Recheck progress from the CLI whenever you need to.

Use status when you want to revisit a run after closing --watch, narrow to one exact variant, or jump directly to a copied generation ID.

docsfy status my-repo
docsfy status my-repo --branch main --provider cursor --model gpt-5.4-xhigh-fast
docsfy status a1b2c3d4-e5f6-7890-abcd-ef1234567890

The first form shows all visible variants for the project. The filtered form targets one exact variant, and the generation ID form goes straight to a single run.

1. Stop a run if progress shows it should not continue.

If you started the wrong branch, chose the wrong model, or no longer want the active run, stop it from the dashboard or the CLI.

docsfy abort my-repo --branch main --provider cursor --model gpt-5.4-xhigh-fast
docsfy abort a1b2c3d4-e5f6-7890-abcd-ef1234567890

When the stop request succeeds, the run changes to aborted. You can then start a fresh run with the settings you want.

Advanced Usage

Use the dashboard for day-to-day monitoring, the CLI watcher for one-off runs, and the WebSocket or JSON output when you need automation.

If you want your own live watcher, connect to the same WebSocket the dashboard uses. A signed-in browser session can open it directly because the session cookie is sent automatically:

const ws = new WebSocket(
  `${location.protocol === 'https:' ? 'wss:' : 'ws:'}//${location.host}/api/ws`
)

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)

  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }))
    return
  }

  if (msg.type === 'progress' || msg.type === 'status_change') {
    console.log(msg.name, msg.status, msg.current_stage ?? '', msg.page_count ?? '')
  }

A new connection gets an initial sync snapshot, then live progress and status_change events for projects you can access. See HTTP API and WebSocket Reference for details.

If you would rather poll than keep a socket open, use JSON output:

docsfy status my-repo --json

Note: Live updates go to admins, the project owner, and users who have been granted access to that project.

Tip: During reruns, incremental_planning usually means docsfy is doing a targeted update, while planning usually means it fell back to a full plan. See Regenerate After Code Changes for details.

Troubleshooting

• --watch stops with a timeout: the CLI waits up to 5 minutes for the next WebSocket message. Run docsfy status my-repo to confirm whether the job is still active, then reconnect with --watch if you still want a live stream.
• --watch says it cannot determine the provider or model: rerun with explicit --provider and --model, or inspect the run first with docsfy status my-repo.
• The dashboard is not updating immediately: the browser reconnects automatically, and after repeated socket failures it falls back to polling about every 10 seconds. Keep the page open and refresh your session if you were signed out.
• A rerun finishes almost immediately: if the current stage is up_to_date, docsfy decided the selected variant already matches the repository state.
• A rerun is taking as long as a full build: if you expected an incremental update but the stage shows planning instead of incremental_planning, docsfy is doing a full plan for that run.
• The run ends in error or aborted: open the selected run, read the error message, and start a new run. See Run Common CLI Workflows for details.# Track Generation Progress

Keep each generation in view so you can tell whether docsfy is still working, already finished, or needs intervention. When you can see the current stage in real time, it is much easier to decide whether to wait, inspect a specific run, or stop and retry.

Prerequisites

• Access to a running docsfy server.
• A signed-in dashboard session or a configured CLI profile with a working key.
• An active run, or a repository you are ready to generate. See Generate Documentation for details.

Quick Example

docsfy generate https://github.com/org/my-repo --watch

This starts a run and keeps the terminal attached to live progress. docsfy prints the project name, branch, status, and generation ID, then streams updates until the run becomes ready, error, or aborted.

Note: --watch only attaches when the server returns generating. If the command returns ready immediately, docsfy decided that variant was already current.

Step-by-Step

1. Start the run in watch mode.

docsfy generate https://github.com/org/my-repo --watch

Use this when you want one command to submit the job and follow it live in the terminal. See CLI Command Reference for details.

1. Keep the dashboard open while the run is active.

Open the dashboard and select the active run from the list. While the connection stays healthy, the page updates automatically and shows:

• the current status: Generating, Ready, Error, or Aborted
• elapsed time while the run is still active
• page count and progress percentage when a plan is available
• the generation ID for later lookup
• an activity log that advances as stages complete

Tip: Copy the generation ID early for long runs. You can use it later with docsfy status or docsfy abort without retyping the branch, provider, and model.

1. Read the stage names as they change.

The terminal watcher and dashboard activity log use these stage names:

1. Recheck progress from the CLI whenever you need to.

Use status when you want to revisit a run after closing --watch, narrow to one exact variant, or jump directly to a copied generation ID.

docsfy status my-repo
docsfy status my-repo --branch main --provider cursor --model gpt-5.4-xhigh-fast
docsfy status a1b2c3d4-e5f6-7890-abcd-ef1234567890

The first form shows all visible variants for the project. The filtered form targets one exact variant, and the generation ID form goes straight to a single run.

1. Stop a run if progress shows it should not continue.

If you started the wrong branch, chose the wrong model, or no longer want the active run, stop it from the dashboard or the CLI.

docsfy abort my-repo --branch main --provider cursor --model gpt-5.4-xhigh-fast
docsfy abort a1b2c3d4-e5f6-7890-abcd-ef1234567890

When the stop request succeeds, the run changes to aborted. You can then start a fresh run with the settings you want.

Advanced Usage

Use the dashboard for day-to-day monitoring, the CLI watcher for one-off runs, and the WebSocket or JSON output when you need automation.

If you want your own live watcher, connect to the same WebSocket the dashboard uses. A signed-in browser session can open it directly because the session cookie is sent automatically:

const ws = new WebSocket(
  `${location.protocol === 'https:' ? 'wss:' : 'ws:'}//${location.host}/api/ws`
)

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)

  if (msg.type === 'ping') {
    ws.send(JSON.stringify({ type: 'pong' }))
    return
  }

  if (msg.type === 'progress' || msg.type === 'status_change') {
    console.log(msg.name, msg.status, msg.current_stage ?? '', msg.page_count ?? '')
  }
}

A new connection gets an initial sync snapshot, then live progress and status_change events for projects you can access. See HTTP API and WebSocket Reference for details.

If you would rather poll than keep a socket open, use JSON output:

docsfy status my-repo --json

Note: Live updates go to admins, the project owner, and users who have been granted access to that project.

Tip: During reruns, incremental_planning usually means docsfy is doing a targeted update, while planning usually means it fell back to a full plan. See Regenerate After Code Changes for details.

Troubleshooting

• --watch stops with a timeout: the CLI waits up to 5 minutes for the next WebSocket message. Run docsfy status my-repo to confirm whether the job is still active, then reconnect with --watch if you still want a live stream.
• --watch says it cannot determine the provider or model: rerun with explicit --provider and --model, or inspect the run first with docsfy status my-repo.
• The dashboard is not updating immediately: the browser reconnects automatically, and after repeated socket failures it falls back to polling about every 10 seconds. Keep the page open and refresh your session if you were signed out.
• A rerun finishes almost immediately: if the current stage is up_to_date, docsfy decided the selected variant already matches the repository state.
• A rerun is taking as long as a full build: if you expected an incremental update but the stage shows planning instead of incremental_planning, docsfy is doing a full plan for that run.
• The run ends in error or aborted: open the selected run, read the error message, and start a new run. See Run Common CLI Workflows for details.

Related Pages

• Generate Documentation
• Run Common CLI Workflows
• HTTP API and WebSocket Reference
• Manage Projects and Variants
• Regenerate After Code Changes