ascend-io
diff --git a/‎AGENTS.md‎
Lines changed: 56 additions & 4 deletions b/‎AGENTS.md‎
Lines changed: 56 additions & 4 deletions
diff --git a/‎Cargo.lock‎
Lines changed: 109 additions & 0 deletions b/‎Cargo.lock‎
Lines changed: 109 additions & 0 deletions
diff --git a/‎crates/ascend-tools-cli/src/cli.rs‎
Lines changed: 36 additions & 19 deletions b/‎crates/ascend-tools-cli/src/cli.rs‎
Lines changed: 36 additions & 19 deletions
@@ -28,7 +28,41 @@ After code changes, always run `bin/check` before committing.
 
 ## authentication
 
-Three env vars are required:
+### instance config (recommended)
+
+Configure named instances in `~/.ascend-tools/config.toml`:
+
+```bash
+ascend-tools instance add default \
+  --service-account-id "asc-sa-..." \
+  --instance-api-url "https://api.instance.ascend.io" \
+  --service-account-key-env ASCEND_SERVICE_ACCOUNT_KEY
+export ASCEND_SERVICE_ACCOUNT_KEY="..."
+```
+
+Config file format (`~/.ascend-tools/config.toml`):
+
+```toml
+default_instance = "production"   # optional, defaults to "default"
+
+[default]
+service_account_id = "asc-sa-abc123"
+instance_api_url = "https://api.myinstance.ascend.io"
+service_account_key_env = "ASCEND_SERVICE_ACCOUNT_KEY"
+
+[staging]
+service_account_id = "asc-sa-def456"
+instance_api_url = "https://api.staging.ascend.io"
+service_account_key_env = "ASCEND_STAGING_KEY"
+```
+
+`service_account_key_env` stores the env var **name** (not the secret). The tool reads that env var at runtime.
+
+Switch instances: `--instance <name>` flag or `ASCEND_INSTANCE` env var.
+
+### environment variables
+
+Three env vars work as a fallback (backward compatible):
 
 | Variable | Description |
 |----------|-------------|
@@ -38,6 +72,13 @@ Three env vars are required:
 
 All three SDKs read these automatically — `Config::from_env()` (Rust), `ascend_tools.Client()` (Python), `new Client()` (JavaScript).
 
+### resolution order
+
+1. CLI flags (`--service-account-id`, etc.) — highest priority
+2. Instance config from TOML (selected by `--instance` or `ASCEND_INSTANCE` env var)
+3. Env vars (`ASCEND_SERVICE_ACCOUNT_ID`, etc.) — fallback
+4. Error
+
 Auth params can also be passed as CLI flags (`--service-account-id`, `--service-account-key`, etc.). Secret values are hidden in `--help` output.
 
 ### local dev
@@ -49,7 +90,12 @@ export ASCEND_INSTANCE_API_URL="https://<workspace>-instance.api.local.ascend.de
 ## CLI reference
 
 ```
-ascend-tools [-o text|json] [-V]
+ascend-tools [-o text|json] [-V] [--instance <NAME>]
+
+  instance add <NAME> --service-account-id <ID> --instance-api-url <URL> [--service-account-key-env <ENV_VAR>]
+  instance list
+  instance remove <NAME>
+  instance set-default <NAME>
 
   workspace list [--environment <NAME>] [--project <NAME>]
   workspace get <TITLE>
@@ -138,9 +184,12 @@ No subcommand prints help.
 ```python
 from ascend_tools import Client
 
-# All params optional — resolved from env vars if not provided
+# All params optional — resolved from instance config or env vars
 client = Client()
 
+# Use a specific named instance from ~/.ascend-tools/config.toml
+client = Client(instance="staging")
+
 # Or explicit — only need the instance API URL
 client = Client(
     service_account_id="asc-sa-...",
@@ -194,9 +243,12 @@ All methods return `dict` or `list[dict]`. All parameters are keyword-only.
 ```javascript
 import { Client } from "ascend-tools";
 
-// All params optional — resolved from env vars if not provided
+// All params optional — resolved from instance config or env vars
 const client = new Client();
 
+// Use a specific named instance from ~/.ascend-tools/config.toml
+const client = new Client(null, null, null, "staging");
+
 // Or explicit
 const client = new Client(
   "asc-sa-...",                      // serviceAccountId
 
@@ -8,6 +8,7 @@ use crate::common::OutputMode;
 use crate::deployment::DeploymentCommands;
 use crate::environment::EnvironmentCommands;
 use crate::flow::FlowCommands;
+use crate::instance::InstanceCommands;
 use crate::otto::OttoCommands;
 use crate::profile::ProfileCommands;
 use crate::project::ProjectCommands;
@@ -24,28 +25,22 @@ pub(crate) struct CliParser {
     #[arg(short, long, global = true, value_enum, default_value_t = OutputMode::Text)]
     output: OutputMode,
 
-    /// Service account ID
-    #[arg(
-        long,
-        global = true,
-        env = "ASCEND_SERVICE_ACCOUNT_ID",
-        hide_env_values = true
-    )]
+    /// Service account ID (overrides instance config and env var)
+    #[arg(long, global = true)]
     service_account_id: Option<String>,
 
-    /// Service account key
-    #[arg(
-        long,
-        global = true,
-        env = "ASCEND_SERVICE_ACCOUNT_KEY",
-        hide_env_values = true
-    )]
+    /// Service account key (overrides instance config and env var)
+    #[arg(long, global = true)]
     service_account_key: Option<String>,
 
-    /// Instance API URL
-    #[arg(long, global = true, env = "ASCEND_INSTANCE_API_URL")]
+    /// Instance API URL (overrides instance config and env var)
+    #[arg(long, global = true)]
     instance_api_url: Option<String>,
 
+    /// Instance name from ~/.ascend-tools/config.toml
+    #[arg(long, global = true, env = "ASCEND_INSTANCE")]
+    instance: Option<String>,
+
     #[command(subcommand)]
     command: Option<Commands>,
 }
@@ -132,6 +127,19 @@ enum Commands {
         #[command(subcommand)]
         command: Option<OttoCommands>,
     },
+    /// Manage instance configurations
+    #[command(
+        long_about = "Manage instance configurations stored in ~/.ascend-tools/config.toml.\n\n\
+            Examples:\n  \
+            ascend-tools instance add production --service-account-id asc-sa-abc --instance-api-url https://api.prod.ascend.io --service-account-key-env ASCEND_PROD_KEY\n  \
+            ascend-tools instance list\n  \
+            ascend-tools instance remove staging\n  \
+            ascend-tools instance set-default production"
+    )]
+    Instance {
+        #[command(subcommand)]
+        command: Option<InstanceCommands>,
+    },
     /// Start an MCP server
     Mcp {
         /// Use HTTP transport instead of stdio
@@ -173,11 +181,16 @@ where
         return crate::skill::handle_skill(command);
     }
 
+    if let Commands::Instance { command } = command {
+        return crate::instance::handle_instance(command, &cli.output);
+    }
+
     if let Commands::Mcp { http, bind } = command {
-        let config = Config::with_overrides(
+        let config = Config::with_overrides_and_instance(
             cli.service_account_id.as_deref(),
             cli.service_account_key.as_deref(),
             cli.instance_api_url.as_deref(),
+            cli.instance.as_deref(),
         );
         let rt = tokio::runtime::Runtime::new()?;
         return if http {
@@ -187,10 +200,11 @@ where
         };
     }
 
-    let config = Config::with_overrides(
+    let config = Config::with_overrides_and_instance(
         cli.service_account_id.as_deref(),
         cli.service_account_key.as_deref(),
         cli.instance_api_url.as_deref(),
+        cli.instance.as_deref(),
     )?;
 
     let client = AscendClient::new(config)?;
@@ -213,7 +227,10 @@ where
         }
         Commands::Flow { command } => crate::flow::handle_flow(&client, command, &cli.output),
         Commands::Otto { command } => crate::otto::handle_otto_cmd(&client, command, &cli.output),
-        Commands::Mcp { .. } | Commands::Skill { .. } | Commands::Signup => unreachable!(),
+        Commands::Instance { .. }
+        | Commands::Mcp { .. }
+        | Commands::Skill { .. }
+        | Commands::Signup => unreachable!(),
     }
 }