apify push --no-wait-for-finish example in --help is broken (Unknown flag provided)

[kuntal1461]

🐛 Bug Report

Command: apify push
Flag: --no-wait-for-finish

---

What happened?

The apify push --help output shows this example under the label "Deploy without waiting for the build to finish":

# Deploy without waiting for the build to finish.
$ apify push --no-wait-for-finish

When a user copies and runs this exact command, it fails immediately — before any Actor logic runs.

---

Steps to Reproduce

apify push --no-wait-for-finish

Output:

Error: Unknown flag provided: --no-wait-for-finish
  To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--no-wait-for-finish"

USAGE
  $ apify push [actorId] [--allow-missing-secrets] [-b <value>]
               [--dir <value>] [-f] [--json] [--open] [-v <value>] [-w <value>]

Exit code: 1

---

Expected Behavior

How we know what the expected behavior should be — two sources confirm it:

1. The --help example itself says:

# Deploy without waiting for the build to finish.
$ apify push --no-wait-for-finish

This tells users that --no-wait-for-finish is the way to do a fire-and-forget deploy.

2. The --wait-for-finish flag description says:

-w, --wait-for-finish=<value>
    In seconds, how long to wait for the build to finish.
    If no value passed, it waits forever.
    To return as soon as the build is queued (fire-and-forget), pass 0.

So the documented intended way to fire-and-forget is --wait-for-finish 0, not --no-wait-for-finish.

Expected: Running apify push --no-wait-for-finish should deploy the Actor and return immediately without waiting for the build — or at minimum should not crash with "Unknown flag provided".

---

Actual Behavior

The command crashes with Error: Unknown flag provided: --no-wait-for-finish and exits with code 1. No deploy happens.

---

Control Case — Correct Form Works Fine

The correct fire-and-forget form (as described in the flag docs) does work:

apify push --wait-for-finish 0

Output:

Error: A valid Actor could not be found in the current directory.

Exit code: 4 — meaning the flag was accepted and the CLI moved on to actor-discovery logic. The parser does not reject it.

This confirms the parser accepts --wait-for-finish 0 but rejects --no-wait-for-finish.

---

Root Cause

--wait-for-finish is declared as a string flag (Flags.string()), not a boolean flag.

Node.js parseArgs (used internally) with allowNegative: true only supports --no-<flag> negation for boolean flags. When applied to a string flag under strict: true, it throws "Unknown flag provided".

The --no-<flag> negation pattern works for flags like --no-purge (which IS a boolean). It does not work for --wait-for-finish (which takes a numeric value).

File: src/commands/actors/push.ts

// Flag is string, not boolean — so --no-wait-for-finish is invalid
'wait-for-finish': Flags.string({
    char: 'w',
    description: '...To return as soon as the build is queued (fire-and-forget), pass 0...',
    required: false,
}),

// The broken example:
{
    description: 'Deploy without waiting for the build to finish.',
    command: 'apify push --no-wait-for-finish',   // ← this does not exist
},

---

Environment

CLI version	1.8.1 (master branch)
Platform	darwin-arm64
Node.js	v24.19.0
Shell	zsh

---

Test Coverage

No tests exist for --wait-for-finish flag parsing anywhere in the test suite. The broken example is only discoverable by manually running the command shown in --help.