{"name":"--ref","slug":"ref","family":"cli","title":"CLI flags","noun":"CLI flag","description":"With `--environment`, base the new session's checkout on a named ref instead of local `HEAD`","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":null,"removed_in":null,"in_current_build":false,"newest_mined":"2.1.308","builds":0,"mined_builds":149,"first_cited":null},"aliases":[],"entries":[{"version":"2.1.304","anchor":"on-branch-ref-revision-pool-options-threaded-through-a","heading":"Task launches can take their starting branch from --on-branch or --ref","line":"A launch path now uses the branch from --on-branch first, then the ref from --ref, and records which flag supplied it","released_at":"2026-10-19 19:47:15","reason":"found in this entry's text"},{"version":"2.1.301","anchor":"cloud-launch-passes-explicit-ref-and-device-too-old-state","heading":"Cloud session launch records which ref you chose and how","line":"Creating a cloud session now notes the ref you named and whether it came from --on-branch or --ref, plus a new file sync state","released_at":"2026-10-15 14:34:23","reason":"found in this entry's text"},{"version":"2.1.290","anchor":"cloud-session-creation-clearer-errors-for-bad-session-ids-a","heading":"Clearer errors when creating a cloud session goes wrong","line":"If the server returns a session id Claude Code cannot use, it now warns a session may exist and points you to claude.ai\/code","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text"},{"version":"2.1.248","anchor":"cloud-and-pool-flags-no-longer-confuse-prompt-detection","heading":"Cloud and pool flags no longer confuse prompt detection","line":"Cloud flags like --pool and --ref no longer swallow their values as your prompt.","released_at":"2026-08-27 20:35:36","reason":"named in this entry, found in this entry's text"},{"version":"2.1.238","anchor":"claude-cloud-explains-when-your-local-changes-cannot-be-uplo","heading":"claude --cloud explains when your local changes cannot be uploaded","line":"`claude --cloud` now says why your local changes could not be uploaded and points you at `--ref`.","released_at":"2026-08-20 18:01:54","reason":"named in this entry, found in this entry's text"},{"version":"2.1.232","anchor":"project-no-longer-starts-a-cloud-session","heading":"--project no longer starts a cloud session","line":"Passing --project alone won't start a cloud session; --ref and --on-branch now need --cloud or --environment.","released_at":"2026-08-13 21:30:53","reason":"named in this entry, found in this entry's text"},{"version":"2.1.224","anchor":"start-a-cloud-session-on-a-self-hosted-environment-with-envi","heading":"Start a cloud session on a self-hosted environment with --environment","line":"Start a cloud session on your own environment with claude --environment, plus hidden --ref and --on-branch companions.","released_at":"2026-08-07 01:36:32","reason":"named in this entry, found in this entry's text"}],"entries_total":7,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"api","path":"manage-claude\/plugins-api","title":"plugins-api","documented":false},{"source":"claude-code","path":"claude-code-on-the-web","title":"Use Claude Code in the cloud","documented":false},{"source":"claude-code","path":"self-hosted-environments-testing","title":"Test self-hosted environments end to end","documented":false}],"docs_total":4,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/ref","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}