@@ -92,13 +92,7 @@ func runScale(ctx context.Context, dockerCli command.Cli, backendOptions *Backen
 		}
 	}
 
-	for key, value := range serviceReplicaTuples {
-		if err := setServiceScale(project, key, value); err != nil {
-			return err
-		}
-	}
-
-	return backend.Scale(ctx, project, api.ScaleOptions{Services: services})
+	return backend.Scale(ctx, project, api.ScaleOptions{Replicas: serviceReplicaTuples})
 }
 
 func setServiceScale(project *types.Project, name string, replicas int) error {
 
@@ -137,7 +137,9 @@ type Compose interface {
 	Viz(ctx context.Context, project *types.Project, options VizOptions) (string, error)
 	// Wait blocks until at least one of the services' container exits
 	Wait(ctx context.Context, projectName string, options WaitOptions) (int64, error)
-	// Scale manages numbers of container instances running per service
+	// Scale sets the number of replicas of the selected services
+	// (ScaleOptions.Replicas) and converges the project to it, creating,
+	// removing and starting containers as needed
 	Scale(ctx context.Context, project *types.Project, options ScaleOptions) error
 	// Export a service container's filesystem as a tar archive
 	Export(ctx context.Context, projectName string, options ExportOptions) error
@@ -158,6 +160,13 @@ type VolumesOptions struct {
 type VolumesSummary = volume.Volume
 
 type ScaleOptions struct {
+	// Replicas maps a service name to the number of replicas it must run.
+	// Scale applies these counts to the project model before converging it.
+	Replicas map[string]int
+	// Services selects the services whose containers may be recreated on
+	// configuration divergence while converging (see CreateOptions.Services);
+	// it does not scale anything by itself. When empty, it defaults to the
+	// keys of Replicas.
 	Services []string
 }
 
 
@@ -17,6 +17,8 @@ package compose
 
 import (
 	"context"
+	"maps"
+	"slices"
 
 	"github.com/compose-spec/compose-go/v2/types"
 
@@ -26,10 +28,31 @@ import (
 
 func (s *composeService) Scale(ctx context.Context, project *types.Project, options api.ScaleOptions) error {
 	return Run(ctx, tracing.SpanWrapFunc("project/scale", tracing.ProjectOptions(ctx, project), func(ctx context.Context) error {
-		err := s.create(ctx, project, api.CreateOptions{Services: options.Services})
+		if err := applyReplicas(project, options.Replicas); err != nil {
+			return err
+		}
+		services := options.Services
+		if len(services) == 0 {
+			services = slices.Collect(maps.Keys(options.Replicas))
+		}
+		err := s.create(ctx, project, api.CreateOptions{Services: services})
 		if err != nil {
 			return err
 		}
-		return s.start(ctx, project.Name, api.StartOptions{Project: project, Services: options.Services}, nil)
+		return s.start(ctx, project.Name, api.StartOptions{Project: project, Services: services}, nil)
 	}), "scale", s.events)
 }
+
+// applyReplicas applies the requested replica counts to the project model,
+// which is what the convergence performed by create/start acts upon.
+func applyReplicas(project *types.Project, replicas map[string]int) error {
+	for name, scale := range replicas {
+		service, err := project.GetService(name)
+		if err != nil {
+			return err
+		}
+		service.SetScale(scale)
+		project.Services[name] = service
+	}
+	return nil
+}
@@ -0,0 +1,42 @@
+/*
+Copyright 2020 Docker Compose CLI authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+package compose
+
+import (
+	"testing"
+
+	"github.com/compose-spec/compose-go/v2/types"
+	"gotest.tools/v3/assert"
+)
+
+func TestApplyReplicas(t *testing.T) {
+	project := &types.Project{
+		Services: types.Services{
+			"web": types.ServiceConfig{Name: "web"},
+			"db":  types.ServiceConfig{Name: "db"},
+		},
+	}
+
+	err := applyReplicas(project, map[string]int{"web": 3})
+	assert.NilError(t, err)
+	web := project.Services["web"]
+	db := project.Services["db"]
+	assert.Equal(t, web.GetScale(), 3)
+	assert.Equal(t, db.GetScale(), 1, "untargeted service keeps its default scale")
+
+	err = applyReplicas(project, map[string]int{"unknown": 1})
+	assert.ErrorContains(t, err, "no such service: unknown")
+}
Original file line number	Diff line number	Diff line change
`@@ -92,13 +92,7 @@ func runScale(ctx context.Context, dockerCli command.Cli, backendOptions *Backen`
`92`	`92`	`}`
`93`	`93`	`}`
`94`	`94`
`95`		`- for key, value := range serviceReplicaTuples {`
`96`		`- if err := setServiceScale(project, key, value); err != nil {`
`97`		`- return err`
`98`		`- }`
`99`		`- }`
`100`		`-`
`101`		`- return backend.Scale(ctx, project, api.ScaleOptions{Services: services})`
	`95`	`+ return backend.Scale(ctx, project, api.ScaleOptions{Replicas: serviceReplicaTuples})`
`102`	`96`	`}`
`103`	`97`
`104`	`98`	`func setServiceScale(project *types.Project, name string, replicas int) error {`