How to Use Variables in Kane CLI

Variables keep credentials and test data out of your objectives. You reference a reusable value or secret by name, so you can run the same test with different inputs without editing the objective text. Context files give the agent standing background information: guidance, conventions, and notes that apply to every run. This page covers how kane-cli finds and merges variables, how to mark a value as secret, and where to put context files for the agent to read.

Variables

Format

Variables are defined in JSON, as an object keyed by variable name. Each entry describes one 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 a string (`8080` becomes `"8080"`). A boolean, object, or array is not accepted as a value. Entries without `value` are ignored.
`secret`	No	boolean	`false`	When `true`, the value is masked in logs and sent to the secrets store instead of being synced as a plain Test Manager variable.
`syntax`	No	string	`{{<name>}}`	Custom placeholder syntax. Defaults to the double-brace form with the variable name.

Usage in Objectives

Reference a variable in the objective with its syntax. With the default syntax, that is {{<name>}}. Variables resolve anywhere Kane CLI types or sets a value: form fields, cookie and localStorage values, and clipboard writes.

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 reaches the agent, Kane CLI rewrites {{email}} to {{global.email}} and the secret {{password}} to a secrets reference. The agent works with the resolved values when the run executes. Saved _test.md files keep the bare {{name}} form.

Loading Order

Kane CLI merges variables from four sources in this order. When two sources define the same key, the later source wins:

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

Within a directory, files are read in alphabetical order, and a later file wins for a duplicate key. A file that is not valid JSON is skipped with a warning.

Inline Variables

Pass a JSON object directly on the command line. Inline variables have the highest precedence.

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

Variables from a File

Point at a single JSON file to load all of its variables at once.

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

The file must be a JSON object whose values are variable entries (see Format).

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/. These files are not the same as {{global.<name>}}, which reads a Test Manager global variable. See Runtime Namespaces.

~/.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 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.

Runtime Namespaces: global, environment, smart

Requires Kane CLI 0.9.0 or later.

Besides your own variables, an objective can use values that Kane CLI fills in at run time. A namespace is the prefix before the dot, such as global. or smart.. It tells Kane CLI where the value comes from:

Reference	Resolves to
`{{global.<name>}}`	A global variable from Test Manager. Locally, a value you pass with the same name (in a variables file or with `--variables`) wins.
`{{environment.<name>}}`	A variable of the run’s Test Manager environment.
`{{smart.<name>}}`	A generated value: a date, random test data, or session info. See Smart Variables.
`{{secrets.<…>}}`, `{{totp.<…>}}`	A secret, or a one-time code generated when it is typed. The agent never sees these values.

How they behave:

Resolved when each objective starts. The agent sees the real value, so it can type it, reason about it, and assert on it. The saved test keeps the reference, not the value, so every replay resolves it fresh. A {{smart.random_email}} is a different address on every run, and in an interactive session on every objective.
{{…}} only. ${global.x} is not a namespace reference. ${…} is reserved for dataset columns.
Two references can sit side by side. {{smart.random_int}}.{{smart.random_int}} is two values joined by a dot.
A value the test stored wins. If an earlier step stored a value under the same name, Kane CLI uses that value.
An unresolved global or environment reference stops the run before step 1, and Kane CLI shows the reason. A smart reference never stops a run. An unknown name resolves to an empty string, so check the spelling.

Smart Variables

Variable	Example value	Format
`{{smart.current_date}}`	`2026-10-15`	`YYYY-MM-DD`
`{{smart.current_day}}`	`Thursday`	Day name
`{{smart.current_month}}`	`October`	Month name
`{{smart.current_month_number}}`	`10`	Two digits
`{{smart.current_year}}`	`2026`	Four digits
`{{smart.current_hour}}`	`14`	24-hour, two digits
`{{smart.current_minute}}`	`05`	Two digits
`{{smart.current_timestamp}}`	`2026-10-15 14:05:09`	`YYYY-MM-DD HH:MM:SS`
`{{smart.current_timezone}}`	`UTC`	Zone name
`{{smart.next_day}}`	`2026-10-16`	Tomorrow, `YYYY-MM-DD`
`{{smart.previous_day}}`	`2026-10-14`	Yesterday, `YYYY-MM-DD`
`{{smart.start_of_week}}`	`2026-10-12`	This week’s Monday
`{{smart.end_of_week}}`	`2026-10-18`	This week’s Sunday
`{{smart.start_of_month}}`	`2026-10-01`	First day of this month
`{{smart.end_of_month}}`	`2026-10-31`	Last day of this month
`{{smart.random_int}}`	`482`	Integer from 100 to 999
`{{smart.random_float}}`	`37.42`	1 to 100, two decimals
`{{smart.random_string_8}}`	`aZ3kP9qL`	8 letters and digits
`{{smart.random_string_56}}`	`Xk2…`	56 letters and digits
`{{smart.random_email}}`	`k3j9x0a1bq@example.com`	10 random characters, then `@example.com`
`{{smart.random_phone}}`	`7294810356`	10 digits
`{{smart.user_name}}`	`jane`	Your username

Smart variables take no arguments. For a date format or offset the table does not have, describe it in the objective instead (“pick the date one week from today”).
Dates and times in a browser run are in UTC, not your machine’s time zone. Keep that in mind around midnight.

Examples:

kane-cli run "Sign up with email {{smart.random_email}} and password {{smart.random_string_8}}, then verify the welcome page"
kane-cli run "Search for hotels in Paris with check-in {{smart.next_day}} and verify results are listed"
kane-cli run "Create a project named Demo {{smart.random_int}} and verify it appears in the project list"

Variables declared by `kane-cli design tests`

When a design session needs a value nobody has provided yet, such as a start URL or a test account, it references the value as {{name}} and declares it as a variable. Before it picks a name, design reads every *.json file in both variable directories and reuses a name you already have instead of inventing a new one. The agent sees only which names exist and whether each one has a value. It never sees the values themselves. For each name it declares, Kane CLI writes an empty stub (the name with a blank value) into .testmuai/variables/assurance.json. It never writes a value. Kane CLI tells you about new stubs 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 in 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 in the step as literal text. Design creates a variable 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}} that an authored step references before the run starts. A name with no value produces a warning, not an error. The run goes ahead and types the name as written, unless an earlier step sets it:

warning: 3 variables have no value

  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.
  A step that sets a name first binds it; anything else is typed as written. Fill the values to bind them.

How to read the warning:

Grouping. The warning groups names by the variables file they belong in (the pool file, such as .testmuai/variables/assurance.json) and names that file once per group.
Test filenames. A test filename appears only when it differs from the file you ran. An @imported unit and a testrun member both show their own filename. A kane-cli run objective shows no location.
Names in no file. If the pool file exists, the warning says Add it to <file>. If there is no pool file yet, it shows the JSON to create.

The check skips these references:

An explicit {{global.*}}. It resolves from Test Manager when the run executes. Only a bare {{name}} is looked up in your variables files.
{{smart.*}}, {{environment.*}}, {{secrets.*}}, and {{totp.*}}, which resolve when the run executes.
A name that an earlier step stores (store the price as 'price').
A name that the test’s own frontmatter variables: declares, even with an empty value.
Replayed steps, which resolve from their recording (tape) and from Test Manager. A testrun run preflight still lists a replayed step’s names, because it checks the file before it knows which steps replay.

${x} is a dataset column reference, not a variables-file reference. If ${x} is not a column of the dataset row the run received, it gets its own warning. In agent mode, the same content arrives as one warning event with code: "unresolved_variables". See Modes of Operation.

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

Global context (default path ~/.testmuai/kaneai/global-memory.md): put guidance that applies to every project and your whole account here. Kane CLI loads it for every run unless you override it. Local context (default path .testmuai/context.md in the current working directory): put guidance here that only makes sense for the project you are testing. Kane CLI loads it automatically when you run kane-cli from a directory that contains it.

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

Use the run flags to point at a different file for a single invocation:

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

If a context file is missing or empty, Kane CLI ignores it without raising an error.

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

​Variables

​Format

​Usage in Objectives

​Loading Order

​Inline Variables

​Variables from a File

​Project-Local Variables

​Global Variables

​Example Variable File

​Secrets

​Runtime Namespaces: global, environment, smart

​Smart Variables

​Variables declared by kane-cli design tests

​Before a run: unresolved variables

​Context Files

​Two Levels

​Example Local Context File

​Override Per Run

​What to Put in Context

Variables

Format

Usage in Objectives

Loading Order

Inline Variables

Variables from a File

Project-Local Variables

Global Variables

Example Variable File

Secrets

Runtime Namespaces: global, environment, smart

Smart Variables

Variables declared by `kane-cli design tests`

Before a run: unresolved variables

Context Files

Two Levels

Example Local Context File

Override Per Run

What to Put in Context