feat: Add apify server commands for Server Actors

docs/reference.md

@@ -466,8 +466,8 @@ DESCRIPTION
 
 USAGE
   $ apify run [--allow-missing-secrets] [--entrypoint <value>]
-              [-i <value> | --input-file <value>] [--profile <value>]
-              [-p | --resurrect]
+              [-i <value> | --input-file <value>] [--port <value>]
+              [--profile <value>] [-p | --resurrect] [--standby]
 
 FLAGS
       --allow-missing-secrets  Allow the command to
@@ -488,6 +488,9 @@ FLAGS
                                this flag or `--input`, the CLI still reads standard
                                input, but stops waiting if input is slow to start or
                                pauses.
+      --port=<value>           The port the Actor's web
+                               server listens on. Use with --standby. Defaults to
+                               4321.
       --profile=<value>        The stored account to use
                                for this command, by name or user ID. See "apify auth
                                list".
@@ -500,6 +503,11 @@ FLAGS
       --resurrect              Whether to keep the default
                                request queue, dataset and key-value store before the
                                run starts.
+      --standby                Run the Actor the way the
+                               platform starts it for its server interface: sets
+                               APIFY_META_ORIGIN=STANDBY and the web server port,
+                               then sends the readiness probe and prints the local
+                               URL.
 ```
 
 ##### `apify validate-schema`
@@ -1946,6 +1954,133 @@ FLAGS
 <!-- task-commands-end -->
 <!-- prettier-ignore-end -->
 
+### Server Actors
+
+These commands let you call a Server Actor's HTTP endpoints and inspect its server interface.
+
+<!-- prettier-ignore-start -->
+<!-- server-commands-start -->
+##### `apify server`
+
+```sh
+DESCRIPTION
+  Send requests to a Server Actor and inspect its server interface.
+
+SUBCOMMANDS
+  server request    Sends an authenticated HTTP request to a
+                    Server Actor's server interface and prints the response.
+  server status     Shows how a Server Actor's server interface
+                    is configured and, for single-tenant Actors, the runs serving
+                    you. Never sends a request to the Actor, so it cannot start a
+                    run.
+  server endpoints  Lists the HTTP endpoints of a Server Actor,
+                    read from the web server schema of the build that serves its
+                    server interface.
+  server url        Prints the URL of a Server Actor's server
+                    interface.
+```
+
+##### `apify server request`
+
+```sh
+DESCRIPTION
+  Sends an authenticated HTTP request to a Server Actor's server interface and 
+  prints the response.
+  The host always comes from the Actor; pass a path, never a full URL. The API 
+  token is sent in the Authorization header and never reaches the Actor.
+
+USAGE
+  $ apify server request [methodOrTarget] [targetOrPath]
+                         [path] [-d <value>] [-H <value>]
+                         [-X GET|POST|PUT|PATCH|DELETE] [-p <value>]
+                         [--profile <value>]
+
+ARGUMENTS
+  methodOrTarget  The HTTP method (defaults to GET), or the Actor
+                  when the method is omitted.
+  targetOrPath    The Actor ID or "username/name" (defaults to the
+                  Actor in the current directory), or the path.
+  path            The path on the Actor's server, starting with
+                  "/". Defaults to "/".
+
+FLAGS
+  -d, --body=<value>     The request body. Use "-" to read
+                         from stdin.
+      -H, --header=<value>   Additional HTTP header(s). Pass a
+                         single "key:value" string, or a JSON object like '{"X-Foo":
+                         "bar", "X-Baz": "qux"}' to send multiple headers.
+      -X, --method=<option>  The HTTP method to use. Defaults to
+                         GET.
+                         <options: GET|POST|PUT|PATCH|DELETE>
+  -p, --params=<value>   Query parameters as a JSON object,
+                         e.g. '{"query": "apify"}'.
+      --profile=<value>  The stored account to use for this
+                         command, by name or user ID. See "apify auth list".
+```
+
+##### `apify server status`
+
+```sh
+DESCRIPTION
+  Shows how a Server Actor's server interface is configured and, for 
+  single-tenant Actors, the runs serving you. Never sends a request to the 
+  Actor, so it cannot start a run.
+
+USAGE
+  $ apify server status [target] [--json]
+                        [--profile <value>]
+
+ARGUMENTS
+  target  The Actor ID or "username/name". Defaults to the Actor in the
+          current directory.
+
+FLAGS
+      --json             Format the command output as JSON.
+      --profile=<value>  The stored account to use for this
+                         command, by name or user ID. See "apify auth list".
+```
+
+##### `apify server endpoints`
+
+```sh
+DESCRIPTION
+  Lists the HTTP endpoints of a Server Actor, read from the web server schema of
+   the build that serves its server interface.
+
+USAGE
+  $ apify server endpoints [target] [--json]
+                           [--profile <value>]
+
+ARGUMENTS
+  target  The Actor ID or "username/name". Defaults to the Actor in the
+          current directory.
+
+FLAGS
+      --json             Format the command output as JSON.
+      --profile=<value>  The stored account to use for this
+                         command, by name or user ID. See "apify auth list".
+```
+
+##### `apify server url`
+
+```sh
+DESCRIPTION
+  Prints the URL of a Server Actor's server interface.
+
+USAGE
+  $ apify server url [target] [--profile <value>]
+
+ARGUMENTS
+  target  The Actor ID or "username/name". Defaults to the Actor in the
+          current directory.
+
+FLAGS
+      --profile=<value>  The stored account to use for this
+                         command, by name or user ID. See "apify auth list".
+```
+<!-- server-commands-end -->
+<!-- prettier-ignore-end -->
+
 ### MCP
 
 Use these commands to configure the Apify MCP server in your AI client.

scripts/generate-cli-docs.ts

@@ -121,6 +121,14 @@ const categories: Record<string, CommandsInCategory[]> = {
 		{ command: Commands.taskPublish },
 		{ command: Commands.taskUnpublish },
 	],
+	'server': [
+		//
+		{ command: Commands.server },
+		{ command: Commands.serverRequest },
+		{ command: Commands.serverStatus },
+		{ command: Commands.serverEndpoints },
+		{ command: Commands.serverUrl },
+	],
 	'mcp': [
 		//
 		{ command: Commands.mcp },

scripts/reference-template.md

@@ -111,6 +111,15 @@ These commands help you manage scheduled and configured Actor runs. Use them to
 <!-- task-commands-end -->
 <!-- prettier-ignore-end -->
 
+### Server Actors
+
+These commands let you call a Server Actor's HTTP endpoints and inspect its server interface.
+
+<!-- prettier-ignore-start -->
+<!-- server-commands-start -->
+<!-- server-commands-end -->
+<!-- prettier-ignore-end -->
+
 ### MCP
 
 Use these commands to configure the Apify MCP server in your AI client.

src/commands/_register.ts

@@ -32,6 +32,7 @@ import { RequestQueuesIndexCommand } from './request-queues/_index.js';
 import { RunCommand } from './run.js';
 import { RunsIndexCommand } from './runs/_index.js';
 import { SecretsIndexCommand } from './secrets/_index.js';
+import { ServerIndexCommand } from './server/_index.js';
 import { TasksIndexCommand } from './task/_index.js';
 import { TelemetryIndexCommand } from './telemetry/_index.js';
 import { TemplatesIndexCommand } from './templates/_index.js';
@@ -49,6 +50,7 @@ export const apifyCommands = [
 	RequestQueuesIndexCommand,
 	RunsIndexCommand,
 	SecretsIndexCommand,
+	ServerIndexCommand,
 	TasksIndexCommand,
 	TelemetryIndexCommand,
 	TemplatesIndexCommand,

src/commands/actors/call.ts

@@ -20,7 +20,8 @@ import { getInputOverride } from '../../lib/commands/resolve-input.js';
 import { runActorOrTaskOnCloud, SharedRunOnCloudFlags } from '../../lib/commands/run-on-cloud.js';
 import { finalizeRun } from '../../lib/commands/run-result.js';
 import { CommandExitCodes, LOCAL_CONFIG_PATH } from '../../lib/consts.js';
-import { error, simpleLog } from '../../lib/outputs.js';
+import { error, info, simpleLog } from '../../lib/outputs.js';
+import { getServerInterfaceHint } from '../../lib/server-actor.js';
 import { getLocalConfig, getCurrentUserInfo, getLoggedClientOrThrow, TimestampFormatter } from '../../lib/utils.js';
 
 export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
@@ -129,6 +130,12 @@ export class ActorsCallCommand extends ApifyCommand<typeof ActorsCallCommand> {
 			providedActorNameOrId: this.args.actorId,
 		});
 
+		const serverInterfaceHint = getServerInterfaceHint(actorData, userFriendlyId);
+
+		if (!this.flags.silent && serverInterfaceHint) {
+			info({ message: serverInterfaceHint });
+		}
+
 		const runOpts: ActorStartOptions = {
 			waitForFinish: 2, // NOTE: We need to wait some time to Apify open stream and we can create connection
 		};

src/commands/actors/push.ts

@@ -57,7 +57,7 @@ const BUILD_LOG_TAIL_LINES = 10;
 interface PushResult {
 	ok: boolean;
 	operation: 'push';
-	actor: { id: string; url: string };
+	actor: { id: string; url: string; standbyUrl?: string };
 	build: { id: string; number: string; status: string; url: string };
 	error?: { phase: 'build'; message: string; logTail: string[] };
 	exitCode?: number;
@@ -621,10 +621,18 @@ Skipping push. Use --force to override.`,
 			process.exitCode = outcome.exitCode;
 		}
 
+		// Read the URL from the API: the hostname format differs between Actors and environments.
+		let standbyUrl: string | undefined;
+
+		if (outcome.ok && actorConfig!.usesStandbyMode) {
+			const pushedActor = (await actorClient.get()) as (Actor & { standbyUrl?: string | null }) | undefined;
+			standbyUrl = pushedActor?.standbyUrl ?? undefined;
+		}
+
 		const result: PushResult = {
 			ok: outcome.ok,
 			operation: 'push',
-			actor: { id: build.actId, url: actorUrl },
+			actor: { id: build.actId, url: actorUrl, ...(standbyUrl && { standbyUrl }) },
 			build: { id: build.id, number: build.buildNumber, status: buildStatus, url: buildUrl },
 		};
 		if (outcome.exitCode !== undefined) {
@@ -651,6 +659,12 @@ Skipping push. Use --force to override.`,
 			'',
 			`Actor URL: ${actorUrl}`,
 			`Build URL: ${buildUrl}`,
+			...(standbyUrl
+				? [
+						`Server interface URL: ${standbyUrl}`,
+						`Send a request: apify server request ${actor.username}/${actor.name} /`,
+					]
+				: []),
 			...(outcome.errorMessage && logTail.length ? ['', 'Reason:', ...logTail] : []),
 		];
 		simpleLog({ stdout: true, message: lines.join('\n') });

src/commands/actors/start.ts

@@ -10,7 +10,8 @@ import { consoleActorUrl, consoleRunUrl } from '../../lib/commands/agent-output.
 import { getInputOverride } from '../../lib/commands/resolve-input.js';
 import { runActorOrTaskOnCloud, SharedRunOnCloudFlags } from '../../lib/commands/run-on-cloud.js';
 import { LOCAL_CONFIG_PATH } from '../../lib/consts.js';
-import { simpleLog } from '../../lib/outputs.js';
+import { info, simpleLog } from '../../lib/outputs.js';
+import { getServerInterfaceHint } from '../../lib/server-actor.js';
 import { getLocalConfig, getCurrentUserInfo, getLoggedClientOrThrow, printJsonToStdout } from '../../lib/utils.js';
 import { ActorsCallCommand } from './call.js';
 
@@ -88,6 +89,12 @@ export class ActorsStartCommand extends ApifyCommand<typeof ActorsStartCommand>
 			providedActorNameOrId: this.args.actorId,
 		});
 
+		const serverInterfaceHint = getServerInterfaceHint(actorData, userFriendlyId);
+
+		if (serverInterfaceHint) {
+			info({ message: serverInterfaceHint });
+		}
+
 		const runOpts: ActorStartOptions = {};
 
 		if (this.flags.build) {