Variables & Context

Variables keep credentials and test data out of your objectives. Context files give the agent persistent background information: guidance, conventions, and notes that apply across runs.

---

Variables

Format

Variables are JSON objects keyed by name. Each entry describes a single variable:

{
  "username": { "value": "alice", "secret": false },
  "api_key":  { "value": "sk-live-...", "secret": true }
}

Field	Required	Type	Default	Description
value	Yes	string	None	The variable's value. A number is accepted and loaded as its string (8080 becomes "8080"), while a boolean, object or array is not a value. Entries without value are ignored.
secret	No	boolean	false	When true, the value is masked in logs and routed to the TestMu AI secrets store instead of being synced as plain Test Manager variables.

Usage in Objectives

Reference variables with {{key}} syntax:

kane-cli run \
  --url https://myapp.com \
  --variables-file ./creds.json \
  "fill the email field with '{{email}}',
   fill the password field with '{{password}}',
   click Login,
   assert the Dashboard is visible"

Before the objective is sent to the agent, {{email}} and {{password}} are rewritten to internal namespaced forms; the agent sees the resolved values at runtime.

Loading Order

Variables are merged from four sources in this order. Later sources override earlier ones for the same key:

1. Global directory: ~/.testmuai/kaneai/variables/*.json
2. Local project directory: .testmuai/variables/*.json (relative to where you invoke kane-cli)
3. File flag: --variables-file <path>
4. Inline flag: --variables '<json>' (highest priority)

Within a directory, files are read in alphabetical order; later files override earlier files for duplicate keys. Files that fail to parse as JSON are skipped with a warning.

Inline Variables

Pass a JSON object directly on the command line:

kane-cli run "Log in as {{username}}" \
  --variables '{"username": {"value": "alice"}}'

Variables from a File

Point at a single JSON file:

kane-cli run "Log in as {{username}}" \
  --variables-file ./vars.json

Project-Local Variables

Drop one or more *.json files into .testmuai/variables/ inside your project's working directory. They load automatically whenever you run kane-cli from that directory.

my-project/
├── .testmuai/
│   └── variables/
│       ├── credentials.json
│       └── urls.json
└── ...

Project-local variables override global variables but are overridden by file and inline flags.

Global Variables

For values you want available across every project on your machine, place *.json files in ~/.testmuai/kaneai/variables/.

~/.testmuai/kaneai/variables/
├── personal.json
└── shared.json

Global variables have the lowest precedence, anything else with the same key wins.

Example Variable File

{
  "app_url": { "value": "https://staging.myapp.com" },
  "admin_email": { "value": "admin@example.com" },
  "admin_password": { "value": "admin_pass_123", "secret": true },
  "customer_email": { "value": "customer@example.com" },
  "customer_password": { "value": "customer_pass_456", "secret": true },
  "test_product_sku": { "value": "PROD-2024-001" }
}

Secrets

Mark a variable as secret by setting "secret": true:

{
  "api_key": { "value": "sk-live-abc123", "secret": true }
}

Secret values are masked in displayed output and logs, and are routed to the TestMu AI secrets store instead of being synced to Test Manager as plain variables. Use this for credentials, tokens, and anything else that should not appear in shareable artifacts.

Variables declared by kane-cli design tests

When a design session needs a value nobody has, such as a start URL or a test account, it references it as {{name}} and declares it. Before choosing a name, design reads every *.json in both variable directories and reuses a name you already have rather than inventing a new one. The agent sees only which names exist and whether each has a value, never the values themselves.

For each name it declares, Kane CLI writes an empty stub into .testmuai/variables/assurance.json, never a value, and tells you during the round (⚒ declared 2 new variables — login_email · login_password (values needed)) and again at the end (2 variable(s) need values — see .testmuai/variables/assurance.json):

{
  "login_email": { "value": "", "secret": false, "description": "the account the login tests sign in with" }
}

Fill value. Kane CLI never overwrites a key that already exists in any of your variable files, so a stub cannot replace a value you set. A value you type in chat stays a literal in the step, and a variable is created only when the value is unknown.

Before a run: unresolved variables

kane-cli run, kane-cli testmd run and kane-cli testrun run check every {{name}} an authored step references before anything starts, with no browser and no session. A name with no value stops the run there, with exit code 2, and the receipt says what each one needs:

✗ 3 variables have no value — nothing was dispatched

  Waiting for a value in .testmuai/variables/assurance.json
    storefront_sign_in_url     step 1
    registered_customer_email  step 2

  Not in any variables file
    checkout_url               step 4

    Add it to .testmuai/variables/assurance.json

  If {{name}} is literal page text, write \{{name}} to keep it as-is.
  Fill the values and run again.

The pool file is named once per group. A test filename appears only when it is not the file you named: an @imported unit and a testrun member both keep theirs, and a kane-cli run objective shows no location at all. A name that is in no file gets Add it to <file> when a pool file exists, or the JSON to create when there is none yet.

There is no flag to bypass the check: fill the value or remove the reference. Never checked are {{smart.*}}, {{environment.*}}, {{secrets.*}} and {{totp.*}} (resolved at run time), a name an earlier step stored (store the price as 'price'), a test's own frontmatter variables:, and replayed steps, which resolve from their tape and from Test Manager, where a replay with a missing value gets a warning line and never a refusal. ${x} is not a variable reference on this path. In agent mode the refusal is one typed error event with code: "unresolved_variables", see Modes of Operation.

warning

Do not commit credential files to version control. Add .testmuai/variables/ to your .gitignore, or use environment variable substitution in CI/CD.

---

Context Files

Context files are plain Markdown files whose contents are passed to the agent alongside your objective. Use them for standing instructions: coding conventions, accounts to use, sites to avoid, or domain knowledge the agent should always have.

Two Levels

Level	Path	Use For
Global	~/.testmuai/kaneai/global-memory.md	Company-wide terminology, shared test accounts, universal patterns
Local	.testmuai/context.md (in project directory)	App-specific navigation, known UI quirks, test environment details

Example Local Context File

# MyApp Staging Context

## Application Overview
MyApp is a SaaS project management tool. Users create projects, invite members, and track tasks.

## Test Environment
- URL: https://staging.myapp.local
- Database resets daily at 2 AM UTC
- File uploads are disabled in staging

## Navigation Patterns
- Main menu is in the left sidebar (hover to expand)
- Settings is under the top-right user avatar menu
- Deep links work: /dashboard/projects/123/tasks

## Known UI Quirks
- The modal close button sometimes needs two clicks
- Date picker defaults to today: click the field to open
- The "Copy Link" toast appears bottom-right for 3 seconds

## Common Test Flows
1. Create a project: Dashboard > "New Project" > fill name > "Create"
2. Invite a member: Project Settings > "Team" > "Invite" > enter email > "Send"
3. Complete a task: Tasks page > click task > "Mark Complete" > confirm dialog

## Test Data
- Existing project for testing: "Test Project" (ID: proj_12345)
- Existing user: john@example.com

Override Per Run

Override either context file for a single run:

kane-cli run "your objective" \
  --global-context ./custom-global.md \
  --local-context ./custom-local.md

If a context file is missing or empty, it is silently ignored, no error is raised.

What to Put in Context

Global context:

• Company terminology and naming conventions
• Standard test account references (no hardcoded values)
• Performance expectations (e.g., "page loads in under 3 seconds")
• Universal navigation patterns

Local context:

• App overview and purpose
• Test environment URL and known limitations
• Navigation patterns specific to this app
• Known UI quirks and workarounds
• Common test flows
• Test data references (IDs, emails: no passwords)

Keep out of context:

• Hardcoded secrets (use variables)
• Large code blocks or logs
• Information that changes frequently