Summary

apify create assumes it is scaffolding a fresh, standalone, single-Actor repository. The platform does not make that assumption — it supports monorepos natively — so anyone with an existing repo has to leave the CLI and wire things by hand.

Three symptoms, one root cause.

Version: apify-cli/1.10.0 (d227b1f), darwin-arm64, node 24.18.0.

1. No way to scaffold into a monorepo

The platform supports Actor monorepos: dockerContextDir in .actor/actor.json, source URLs of the form #branch:folder, the ACTOR_PATH_IN_DOCKER_CONTEXT build arg, and an official apify/actor-monorepo-example.

The CLI has no corresponding flag. To get an Actor into actors/my-actor/ I had to:

mkdir actors && cd actors
apify create my-actor --template project_cheerio_crawler_ts --skip-git-init
# then hand-edit .actor/actor.json to add "dockerContextDir"

dockerContextDir is the part most likely to be got wrong: it is resolved relative to .actor/, and when omitted the build context defaults to the repository root — which silently breaks the template's COPY package*.json ./. That is a confusing failure to debug, and it is the CLI that knows where it just placed the Actor.

Suggested:

apify create my-actor --template <t> --into actors/

placing the Actor at actors/my-actor/ and writing the correct dockerContextDir automatically.

2. --source github cannot target a subdirectory

--source github is otherwise the smoothest path in the CLI — it creates the repo, clones it, and wires an Actor that builds from it in one command. But it always produces a fresh repo with the Actor at the root.

That makes it unusable for anyone who already has a repository, or who wants more than one Actor. The platform side already supports what is needed (https://github.com/user/repo#main:actors/my-actor); only the CLI can't express it.

Suggested: allow --git-repo owner/name to point at an existing repo, plus a path, and set the Actor's Git URL to the #branch:dir form.

3. Nested git repo is the default inside an existing repo

The command automatically initializes a git repository in the newly created Actor directory.

Inside an existing working tree that is almost never wanted — it creates a nested repository whose contents the outer repo cannot track. I only avoided it because I happened to know --skip-git-init existed.

Suggested: walk up for an enclosing .git and default to skipping when one is found. Keep --git-init to force the old behaviour.

Why these belong together

All three are the same assumption — one Actor, one repo, nothing above it. Fixing the placement story fixes all three, and the platform already supports the layouts the CLI cannot produce.

Related: #1424 (help text routing agents to the wrong tool).