From b95c0974fc8e507f6057f473411575d9820569c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9dric=20Halber?= <cedric@braintrustdata.com>
Date: Wed, 29 Jul 2026 15:57:01 -0700
Subject: [PATCH] feat: warn that `bt setup` is deprecated

---
 src/main.rs      |  2 +-
 src/setup/mod.rs | 28 ++++++++++++++++++++++++++--
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/src/main.rs b/src/main.rs
index 5f12e60f..39039405 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -79,7 +79,7 @@ Data & evaluation
 
 Additional
   docs         Manage workflow docs for coding agents
-  setup        Configure Braintrust setup flows
+  setup        Configure Braintrust setup flows (deprecated: use curl -fsSL https://braintrust.dev/wizard/setup.sh | sh)
   status       Show current org and project context
   update       Update bt in-place
 
diff --git a/src/setup/mod.rs b/src/setup/mod.rs
index 45ebfbcd..d991b203 100644
--- a/src/setup/mod.rs
+++ b/src/setup/mod.rs
@@ -24,6 +24,22 @@ use crate::http::ApiClient;
 use crate::ui::{self, with_spinner};
 use crate::utils::app_project_url;
 
+/// One-line deprecation notice shown in `bt setup` / `bt docs` help text.
+const SETUP_DEPRECATED_HELP: &str =
+    "Deprecated: use curl -fsSL https://braintrust.dev/wizard/setup.sh | sh";
+
+/// Multi-line deprecation warning printed to stderr when `bt setup` / `bt docs` run.
+const SETUP_DEPRECATED_WARNING: &str = "\
+bt setup has been deprecated, use the command below instead:\n\n    curl -fsSL https://braintrust.dev/wizard/setup.sh | sh";
+
+fn print_setup_deprecation_warning(base: &BaseArgs) {
+    if base.json {
+        return;
+    }
+    eprintln!("{}", SETUP_DEPRECATED_WARNING);
+    eprintln!();
+}
+
 mod agent_stream;
 mod docs;
 mod sdk_install_docs;
@@ -61,12 +77,15 @@ const ALL_WORKFLOWS: [WorkflowArg; 5] = [
 ];
 
 #[derive(Debug, Clone, Args)]
-#[command(after_help = "\
+#[command(
+    before_help = SETUP_DEPRECATED_HELP,
+    after_help = "\
 Examples:
   bt setup --agent cursor --workflow observe
   bt setup skills --agent codex --global
   bt setup mcp --agent codex
-")]
+"
+)]
 pub struct SetupArgs {
     #[command(subcommand)]
     command: Option<SetupSubcommand>,
@@ -136,12 +155,16 @@ pub struct SetupArgs {
 #[derive(Debug, Clone, Subcommand)]
 enum SetupSubcommand {
     /// Configure coding-agent skills to use Braintrust
+    #[command(before_help = SETUP_DEPRECATED_HELP)]
     Skills(AgentsSetupArgs),
     /// Download instrumentation docs and run a coding agent to instrument this repo
+    #[command(before_help = SETUP_DEPRECATED_HELP)]
     Instrument(InstrumentSetupArgs),
     /// Configure MCP server settings for coding agents
+    #[command(before_help = SETUP_DEPRECATED_HELP)]
     Mcp(AgentsMcpSetupArgs),
     /// Diagnose coding-agent setup for Braintrust
+    #[command(before_help = SETUP_DEPRECATED_HELP)]
     Doctor(AgentsDoctorArgs),
 }
 
@@ -566,6 +589,7 @@ struct SkillsAliasResult {
 }
 
 pub async fn run_setup_top(base: BaseArgs, mut args: SetupArgs) -> Result<()> {
+    print_setup_deprecation_warning(&base);
     // Deprecated flag: --no-mcp-skill is equivalent to --no-skills --no-mcp
     if args.no_mcp_skill {
         args.no_skills = true;