Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / CLI flags

--environment

cli never mined documented JSON

A Claude Code CLI flag, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.

Create a new cloud session that runs on the self-hosted environment with the given ID. Environment IDs start with ccpool_. See --environment dispatch behavior for dispatch behavior and the flag combinations it rejects. Requires Claude Code v2.1.224 or later

Anthropic's own wording. Read off CLI reference, captured 2026-09-26.

First seen — never in a mined build
Last seen — never in a mined build
Builds0 / 149on this box, as of v2.1.308
Written about v2.1.224 first named in a changelog, 7 Aug 2026

In the changelogs

24

Releases whose published page names --environment.

  1. v2.1.295
    --environment now reads environment IDs and names, but still only runs pool IDs

    --environment now recognises IDs starting with env_ and plain names, but only IDs starting with ccpool_ actually work so far

    found in this entry's text

  2. v2.1.288
    Headless cloud session errors now name the flag you actually used

    Errors when starting a cloud session without the interactive screen now name the flag you used instead of always saying --environment

    found in this entry's text

  3. v2.1.288
    Errors for conflicting cloud session options can name a different option

    Errors about conflicting --cloud or --environment options no longer always name --environment or always start with Error:

    found in this entry's text

  4. v2.1.287
    CLAUDE.md nested loading and an --environment error message reworked

    The code that loads nested CLAUDE.md files was simplified, and the error for combining --environment with --cloud is now built in parts

    found in this entry's text

  5. v2.1.287
    Headless cloud sessions stop early if they were not started as cloud sessions

    A cloud session without the interactive screen now stops with an error if Claude Code did not recognise it as a cloud launch at start-up

    found in this entry's text

  6. v2.1.287
    Cloud sessions without a monorepo get a default environment

    With the no-monorepo option, --environment now falls back to a default environment ID, and its conflict error messages have been reworded

    found in this entry's text

  7. v2.1.287
    Cloud sessions created with --environment pass on a no-monorepo option

    Creating a cloud session with --environment now passes a no-monorepo option along with the environment ID

    found in this entry's text

  8. v2.1.287
    --cloud stops early when it would need a keyboard it can't read

    If --cloud would open a session in your terminal but there is no keyboard to read from, Claude Code now exits with an error before creating it

    found in this entry's text

  9. v2.1.285
    Cloud sessions started with --environment prepare to pass on blocked tools

    Creating a cloud session with --environment can now send a list of blocked tools, though that list is always empty in this build

    found in this entry's text

  10. v2.1.281
    Hidden claude -p --cloud headless cloud-print path added, but compiled off

    Code for a headless claude -p --cloud run is added, but the switch that enables it returns false, so no one can use it in 2.1.281

    found in this entry's text

  11. v2.1.268
    Remote-session org-policy denials now emit telemetry

    Blocked remote-session actions from org policy now emit a tengu_org_policy_denied telemetry event

    found in this entry's text

  12. v2.1.248
    Cloud and pool flags no longer confuse prompt detection

    Cloud flags like --pool and --ref no longer swallow their values as your prompt.

    named in this entry, found in this entry's text

  13. v2.1.246
    --no-home-settings replaced by --forward-home-settings <true|false>

    The hidden --no-home-settings flag becomes --forward-home-settings true or false, so you can force it on.

    found in this entry's text

  14. v2.1.246
    Forwarding your home settings to a cloud session now records explicit consent

    Forwarding your home settings to a cloud session now records your consent separately from permission.

    named in this entry, found in this entry's text

  15. v2.1.242
    /cloud-plugins and a matching opt-in for sending this machine's settings to cloud sessions

    You now decide separately whether cloud sessions may use your plugins and your local settings.

    found in this entry's text

  16. v2.1.232
    --project no longer starts a cloud session

    Passing --project alone won't start a cloud session; --ref and --on-branch now need --cloud or --environment.

    named in this entry, found in this entry's text

  17. v2.1.229
    Whitespace-only prompts are rejected for --cloud and --environment

    Whitespace-only prompts on --cloud and --environment are rejected instead of sent empty.

    named in this entry, found in this entry's text

  18. v2.1.224
    "pool" renamed to "environment" in runner flags, old names still work

    Runner "pool" flags are renamed to "environment"; old names still work but warn.

    named in this entry

  19. v2.1.224
    Create a cloud session without a terminal

    Create a cloud session straight from the command line with --environment and a prompt, optionally as JSON.

    named in this entry, found in this entry's text

  20. v2.1.224
    Clearer error when --bg and --environment are combined

    Combining --bg and --environment now explains they are different backends and shows the right command.

    named in this entry, found in this entry's text

  21. v2.1.224
    Start a cloud session on a self-hosted environment with --environment

    Start a cloud session on your own environment with claude --environment, plus hidden --ref and --on-branch companions.

    named in this entry, found in this entry's text

  22. v2.1.224
    Flag-conflict error names the flag you actually used

    The cloud-session conflict error now blames --environment, the flag you actually typed.

    named in this entry, found in this entry's text

  23. v2.1.224
    Local runner spawn writes into ./runner-setup and checks 127.0.0.1:8080

    The setup wizard spawns a detached runner into ./runner-setup and warns it outlives your session.

    named in this entry

  24. v2.1.224
    cloud CLI: piped stdin no longer silently overrides a task description

    Piped input no longer silently overrides a task description you passed to --cloud.

    named in this entry, found in this entry's text

First cited

7

The earliest release whose published evidence quoted --environment was v2.1.224, 7 Aug 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.

ReleaseDateThe span that was quoted
v2.1.2247 Aug 2026--bg and --environment are different backends. Use `claude -p '<task>' --environment <id>` directly to start a session on the environment.
v2.1.2247 Aug 2026Error: --environment with --cloud <description> cannot also take piped stdin. Pass the task as the description, or drop --cloud.
v2.1.2247 Aug 2026Error: non-interactive --environment requires a prompt (positional or stdin). Run from a TTY for an interactive cloud session.
v2.1.24224 Aug 2026"Don't send this machine's settings (CLAUDE.md, rules, output styles, preferences, portable permission rules) into the cloud session this launch creates or attaches to. Requires --cloud or --environment."
v2.1.24625 Aug 2026Error: --forward-home-settings says whether this machine's settings go into a cloud session; pass --cloud (a new session, or one to attach to) or --environment
v2.1.2871 Oct 2026--environment cannot be combined with

1 further span in the ledger name it. The list above is the earliest first and stops at 6.

Presence across releases

0

The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.

Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.

Feedback