| name | testerarmy-cli |
| description | Use TesterArmy CLI to create, organize, and run dashboard-managed QA tests. Prefer saved tests, groups, project context, credentials, and remote runs over one-off local prompts. Trigger when defining regression coverage or adding QA flows. |
| license | MIT |
| metadata | {"author":"TesterArmy","tags":"testerarmy, qa, cli, dashboard-tests, regression"} |
TesterArmy CLI
Create dashboard-managed QA coverage with ta / testerarmy.
The CLI is a control plane for the TesterArmy dashboard: manage projects,
environments, credentials, and saved tests, and queue remote runs that execute
in TesterArmy cloud. ta tests run queues remote dashboard runs by default.
Use local execution (ta run "..." or ta tests run --local) only for quick
exploration.
When to Use
- Create persistent QA coverage for a feature or product area.
- Convert acceptance criteria into dashboard tests.
- Add or update smoke, regression, auth, billing, onboarding, or mobile flows.
Setup
Check auth:
ta status --json
If needed:
ta auth
ta auth --api-key <key>
TESTERARMY_API_KEY=<key> ta status --json
ta signout
ta logout
Most commands that call the API accept --api-key <key> and --base-url <url>.
Use env vars or saved auth by default.
Discover scope:
ta projects list --json
ta projects get <projectId> --json
ta groups list --project <projectId> --json
ta tests list --project <projectId> --json
Use IDs exactly as returned.
Project Context
Create a project:
echo '{"name":"Example","url":"https://example.com","projectType":"web"}' | ta projects create --json
echo '{"name":"Example staging"}' | ta projects update <projectId> --json
ta projects files <projectId> --json
Project commands: list, get, create, update, delete, environments,
environments-create, environments-delete, credentials,
credentials-create, files.
Manage saved environments (remote run targets such as Staging or QA):
ta projects environments <projectId> --json
ta projects environments-create <projectId> --name Staging --url https://staging.example.com --json
ta projects environments-delete <projectId> <environmentId> --json
Production and PR Preview are built-in environments and cannot be deleted.
Target a saved environment on runs with --env <nameOrSlug> or
--project-environment-id <id>.
Delete projects only when explicitly requested:
ta projects delete <projectId> --json
Store app knowledge:
ta memories list --project <projectId> --json
echo '{"category":"site_structure","title":"Auth route","content":"Login is at /login","importance":"high"}' | ta memories create --project <projectId> --json
ta memories delete <memoryId> --project <projectId> --json
Memory categories: site_structure, test_insights, user_preferences.
Create credentials for login or inbox flows:
ta projects credentials <projectId> --json
echo '{"kind":"login","label":"Admin","username":"admin@example.com","password":"secret"}' | ta projects credentials-create <projectId> --json
echo '{"kind":"inbox","label":"Signup inbox"}' | ta projects credentials-create <projectId> --json
Never print real secrets in final messages.
Tests
Create:
echo '{"title":"Login flow","description":"User can sign in and reach the dashboard","steps":[{"title":"Navigate to /login","type":"act"},{"title":"Sign in with the saved admin credentials","type":"login","credentialId":"<credentialId>"},{"title":"Dashboard loads and shows the project list","type":"assert"}]}' | ta tests create --project <projectId> --json
Create in a group:
echo '{"title":"Pricing CTA","steps":[{"title":"Open /pricing","type":"act"},{"title":"Click the primary CTA","type":"act"},{"title":"Signup or dashboard flow starts","type":"assert"}]}' | ta tests create --project <projectId> --group <groupId> --json
Payload:
{
"title": "string, required",
"description": "string, optional",
"platform": "web or mobile, optional",
"steps": [
{ "title": "User action", "type": "act" },
{ "title": "Expected result", "type": "assert" },
{ "title": "Login instruction", "type": "login", "credentialId": "uuid" },
{ "title": "Use temporary email", "type": "login", "temporaryEmail": true },
{ "title": "Upload the sample invoice PDF", "type": "files" },
{ "title": "Screenshot label", "type": "screenshot" }
]
}
Write good steps:
- Write plain-language instructions you would give to a teammate.
- Describe the user's intent, not selectors, waits, DOM structure, or component names.
- Give each step one clear job with a clear stopping point.
- Split actions and checks into separate steps.
- Use labels visible in the UI, such as
Pricing, New Project, Save, or Invite teammate.
- Include business context that disambiguates the goal, such as project names, emails, plan names, or expected statuses.
- Make assertions specific enough to pass or fail confidently.
- Quote exact copy only when exact copy matters; otherwise describe the expected meaning.
Examples:
| Avoid | Write |
|---|
Click the button with class .nav-item:nth-child(3), wait 500ms, then assert URL contains /pricing. | Open the Pricing page from the header. |
Log in, create a project, invite a teammate, run a test, and verify the result. | Split into focused steps: log in, create the project, invite the teammate, run the test, then verify the result. |
Add the Pro plan to the cart and make sure the cart is correct. | Add the Pro plan to the cart. then Verify the cart shows the Pro plan with the correct monthly price. |
Verify the dashboard looks good. | Verify the dashboard shows a Projects card, a Recent Runs card, and no visible error banner. |
Before creating or updating a test, check:
- Could a teammate follow these steps without seeing the code?
- Does each step have one clear intent?
- Are actions and assertions split?
- Are user-visible labels included where useful?
- Are credentials handled by a
login step or saved project credentials?
- Is each expected result specific enough to evaluate?
Rules:
- Cover one user journey.
- Prefer 3-10 meaningful steps.
- Use
act for navigation, clicks, typing, and other user actions.
- Use
assert for visible outcomes, persisted state, email delivery, or URL changes.
- Use
login with credentialId or temporaryEmail; do not put passwords in step titles.
- Use
files for uploading attached files.
- Use
screenshot only for important visual checkpoints.
- Do not hide login, uploads, screenshots, or assertions inside broad action steps.
- Maximum 50 steps per test.
Inspect before changing:
ta tests list --project <projectId> --json
ta tests get <testId> --json
Update title, description, steps, or enabled:
echo '{"title":"Updated login smoke"}' | ta tests update <testId> --json
echo '{"steps":[{"title":"Open /login","type":"act"},{"title":"Sign in","type":"login","credentialId":"<credentialId>"},{"title":"Dashboard is visible","type":"assert"}]}' | ta tests update <testId> --json
echo '{"enabled":false}' | ta tests update <testId> --json
Replacing steps requires the complete array.
Toggle a test without deleting it:
ta tests disable <testId> --json
ta tests enable <testId> --json
Delete only when explicitly requested:
ta tests delete <testId> --json
Groups
Create suites:
ta groups list --project <projectId> --json
ta groups get <groupId> --json
echo '{"projectId":"<projectId>","name":"Smoke"}' | ta groups create --json
echo '{"name":"Core smoke"}' | ta groups update <groupId> --json
ta groups add-test <groupId> <testId> --json
ta groups remove-test <groupId> <testId> --json
Delete non-default groups only when explicitly requested:
ta groups delete <groupId> --json
Common groups: Smoke, Auth, Core journeys, Mobile smoke.
Runs
Modes:
- Default/remote: queues the saved test in TesterArmy cloud; results show up in the dashboard.
--local: fetches the saved test, then runs it on this machine.
Remote validation (default):
ta tests run <testId> --wait --json
ta tests run <testId> --env staging --wait --json
ta tests run --group <groupId> --project <projectId> --wait --json
ta tests run <testId> --platform ios --app-id <appId> --wait --json
ta tests run <testId> --platform android --app-id <appId> --wait --json
Local debugging:
ta tests run <testId> --local --url http://localhost:3000 --json
ta tests run --group <groupId> --project <projectId> --local --url http://localhost:3000 --parallel 3 --json
Defaults:
- No flag: remote cloud execution (dashboard run).
--local: local browser execution on this machine.--wait: wait for remote results.--env <nameOrSlug>: target a saved project environment (remote runs pass its ID; local runs use its URL).- Local-only flags such as
--headed, --browser, --timeout, and --system-prompt-file are ignored for remote runs.
- Local runs can use
--headed, --browser chrome|firefox|safari, --timeout, --output, --debug, and --system-prompt-file.
- Remote runs can use
--wait-timeout, --wait-interval, --output, --platform web|ios|android, --app-id, and --project-environment-id.
- Remote group runs can use
--environment production|staging|preview.
- Remote single-test runs can use
--mode fast|deep.
Runs:
ta runs list --project <projectId> --json
ta runs get <runId> --json
ta runs wait <runId> --timeout 600000 --json
ta runs cancel <runId> --json
Mobile App Coverage
Upload an iOS Simulator app or Android APK before cloud runs:
ta upload-app --app-path ios/build/Build/Products/Release-iphonesimulator/MyApp.app --project <projectId> --json
ta upload-app --app-path MyApp.apk --project <projectId> --remove-after 3600 --json
ta tests run <testId> --platform ios --app-id <appId> --wait --json
ta tests run <testId> --platform android --app-id <appId> --wait --json
Supported uploads: .app, .app.zip, .zip for iOS Simulator apps and .apk
for Android. Use --remove-after <seconds> to auto-delete uploaded apps.
Local Prompt
ta run <prompt> runs an ad hoc local browser test:
ta run "check pricing CTA" --url https://example.com --json
Useful flags: --headed, --browser chrome|firefox|safari, --timeout,
--output, --debug, and --system-prompt-file.
Use only to explore before creating or updating dashboard tests. Use
ta tests create and ta tests run --group for durable workflows that run
remotely on the dashboard.
Reporting
Report:
- Project ID/name
- Test IDs and titles created or updated
- Group IDs/names touched
- Remote validation command and result, if run
- Run ID or artifact/output path, if available
Do not claim durable coverage unless ta tests create or ta tests update ran.
References
