Jira — Other

simply atlassian jira fields

List Jira fields, including custom field ids.

Flags

• --custom — Only custom fields.
• --search <value> — Match against the field name or id, case-insensitively.
• --limit <value> — Maximum number of fields to show. (default: 50)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Global

• --json — the raw API payload, for scripts and agents.

This is what makes —body usable on issue create and update. A custom field is addressed by an id like customfield_10016, which differs between instances and cannot be guessed — so without this command the escape hatch for untyped fields is unusable by anyone who has not read it off an admin screen. —search matches the name or the id, so it answers both “what is Story Points called” and “what is customfield_10016”.

Examples

simply atlassian jira fields --custom

simply atlassian jira fields --search "story points"

simply atlassian jira fields --search customfield_10016 --json

simply atlassian jira open

Open a Jira issue or project in the browser.

Flags

• --print — Print the URL without opening a browser.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Global

• --json — the raw API payload, for scripts and agents.

Builds the browser URL for an issue or project and opens it in the default browser. Use —print (or —url) to print the URL without launching a browser.

Examples

simply atlassian jira open PROJ-123

simply atlassian jira open PROJ --print

simply atlassian jira open PROJ-123 --json

simply atlassian jira project versions

List a project’s versions.

Flags

• --limit <value> — Maximum number of versions to show. (default: 25)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Global

• --json — the raw API payload, for scripts and agents.

Versions are how Jira models releases. The ID column is what sets fixVersions through —body on issue create or update.

Examples

simply atlassian jira project versions PROJ

simply atlassian jira project versions PROJ --json

simply atlassian jira projects

List Jira projects.

Flags

• --limit <value> — Maximum number of projects to show. (default: 25)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Global

• --json — the raw API payload, for scripts and agents.

The KEY column is the point: it is what every other command takes and what a caller most often does not have. Cloud paginates this endpoint and Server/DC returns the whole list; both are handled.

Examples

simply atlassian jira projects

simply atlassian jira projects --limit 100 --json

simply atlassian jira xray fields

Show which Jira fields hold Xray’s data on this instance.

Flags

• --refresh — Rediscover and rewrite the instance record first.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Xray’s field ids are assigned when the app is installed, so they differ between instances. The first Xray command against an instance discovers them — by schema type, never by display name — along with the Xray issue types, and saves the result as an instance record that later commands read instead of asking again. This command shows that record: the role each field plays, its id, name and schema type, the Xray fields no role claims, and where the record lives.

If two fields claim one role (an app reinstall can leave orphans), commands that need it refuse to guess; pin the right id under “overrides” in the record, which survives —refresh.

Examples

simply atlassian jira xray fields

simply atlassian jira xray fields --refresh

simply atlassian jira xray fields --json

simply atlassian jira xray path list

Show a project’s test repository folder tree, with test counts.

Flags

• --project <value> — Project key. (required)
• --path <value> — Start at this folder instead of the repository root.
• --depth <value> — Levels of subfolders to show below the starting folder.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Paths are written the way Xray stores them, with a leading slash (/O&M/Accounts), and are what “test list —project X —path” and “test export —project X —path” take. —path starts the tree at a subfolder, with or without the leading slash; —depth limits how many levels below it are shown. —json returns the nested structure: { name, path, id, testCount, folders }.

Examples

simply atlassian jira xray path list --project OM

simply atlassian jira xray path list --project OM --path "/O&M" --depth 1

simply atlassian jira xray path list --project OM --json

simply atlassian jira xray plan list

List the Test Plans in a project, with how many tests each holds.

Flags

• --project <value> — Project key. (required)
• --jql <value> — Extra JQL ANDed onto the project, in parentheses so it cannot widen it.
• --search <value> — Text in the summary or description, matched as typed: no wildcards or operators.
• --fields <value> — Extra fields to return, added to the defaults. Comma-separated or repeated. (repeatable)
• --limit <value> — Maximum number to return. (default: 25)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

People rarely know a test plan key by heart; this finds it. The KEY column is what “test list —plan” takes. —jql and —search narrow the list as they do for “test list”. —json returns the raw search envelope, like “issue search”: { issues, total, pages, complete }.

Examples

simply atlassian jira xray plan list --project OM

simply atlassian jira xray plan list --project OM --search release

simply atlassian jira xray plan list --project OM --jql "status != Closed" --json

simply atlassian jira xray set list

List the Test Sets in a project, with how many tests each holds.

Flags

• --project <value> — Project key. (required)
• --jql <value> — Extra JQL ANDed onto the project, in parentheses so it cannot widen it.
• --search <value> — Text in the summary or description, matched as typed: no wildcards or operators.
• --fields <value> — Extra fields to return, added to the defaults. Comma-separated or repeated. (repeatable)
• --limit <value> — Maximum number to return. (default: 25)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

People rarely know a test set key by heart; this finds it. The KEY column is what “test list —set” takes. —jql and —search narrow the list as they do for “test list”. —json returns the raw search envelope, like “issue search”: { issues, total, pages, complete }.

Examples

simply atlassian jira xray set list --project OM

simply atlassian jira xray set list --project OM --search release

simply atlassian jira xray set list --project OM --jql "status != Closed" --json

simply atlassian jira xray test create

Create an Xray test, with its steps or definition.

Flags

• --dry-run — Print the request that would be sent and exit without sending it.
• --project <value> — Project key the test belongs to.
• --verifies <value> — A requirement this test verifies, which gets a link. Repeatable.
• --file <value> — Path to one test record, as “test get —json” prints it, or one line of “test export —format jsonl”.
• --summary <value> — The summary.
• --type <value> — manual, cucumber, generic, or another type the field allows.
• --step <value> — A step, as ‘action|data|result’. Repeatable; a literal pipe is written |.
• --gherkin <value> — The Cucumber scenario.
• --gherkin-file <value> — Path to a file holding the Cucumber scenario.
• --definition <value> — The generic test definition.
• --field <value> — Another field, as role=value. Repeatable.
• --body <value> — Raw JSON request body, merged underneath.
• --body-file <value> — Path to a file holding the raw JSON request body.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Takes a record from “test get —json”, flags, or both, with flags winning. The type is inferred from the steps, Gherkin or definition unless —type says. Steps go in the same request as the issue, so a test is created with them or not at all. —verifies links the requirement it tests.

Keys of a record this does not write, such as links and preconditions, are named in a note. A step that calls another test is refused. Returns the test read back. Xray credentials have no read-only scope, so ATLASSIAN_READ_ONLY is the only guard against an unintended write.

Examples

simply atlassian jira xray test create --project OM --summary "Reset a password" --step "Open Users||List shown" --verifies OM-40

simply atlassian jira xray test create --project OM --summary "Log in" --gherkin-file ./login.feature

simply atlassian jira xray test create --project OM --file ./test.json --summary "A copy" --dry-run

simply atlassian jira xray test export

Export full test records for a project, plan, set, or folder.

Flags

• --project <value> — Project key: every Test in the project, or the folder —path names in it.
• --plan <value> — Test Plan key: its tests, including any added through a Test Set.
• --set <value> — Test Set key: its tests.
• --path <value> — Test repository folder inside —project, such as “/O&M/Accounts”; ”/” is the root.
• --recursive — With —path, include tests in subfolders.
• --jql <value> — Extra JQL ANDed onto the scope, in parentheses so it cannot widen it.
• --search <value> — Text in the summary or description, matched as typed: no wildcards or operators.
• --linked-to <value> — Only tests linked to any of these issues, by any link type. Comma-separated or repeated. (repeatable)
• --fields <value> — Extra fields to return, added to the defaults. Comma-separated or repeated. (repeatable)
• --format <value> — Output format, written to stdout. Ignored with —json. (default: json; one of: json, jsonl, markdown)
• --limit <value> — Maximum number of tests to export. (default: 1000)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

The bulk form of “test get”, with the scopes and filters of “test list”. Each test becomes one export record — key, summary, status, type, path, preconditions, steps, definition, links, plans, sets, and any —fields — whose shape is documented as a contract in the Xray guide.

Pages of 100 tests are fetched one after another, with progress on stderr; stdout carries only the export. —format jsonl writes one record per line as pages arrive, which suits large exports and pipelines; markdown writes one section per test. Something you cannot see — a precondition, or a link into a project you cannot browse — is skipped and noted on stderr, never fatal, as is step data this version does not interpret, which is kept under the step’s “extra”. Reaching —limit is noted on stderr and still exits 0.

—json returns { records, total, complete, notes } instead, so a script can detect truncation. It replaces —format and the progress lines.

Examples

simply atlassian jira xray test export --plan OM-7 > plan.json

simply atlassian jira xray test export --project OM --path "/O&M/Accounts" --recursive --format jsonl

simply atlassian jira xray test export --project OM --linked-to OM-40,OM-41 --fields components,labels

simply atlassian jira xray test export --set OM-31 --format markdown > tests.md

simply atlassian jira xray test get

Show one Xray test: steps, definition, links, plans, sets, and path.

Flags

• --fields <value> — Extra fields to return, added to the defaults. Comma-separated or repeated. (repeatable)
• --raw — Print the underlying Jira issue as JSON instead.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Assembles a test from its Jira issue and Xray’s fields: the type, the steps (or the Cucumber or generic definition), preconditions, every issue link — which is how the requirement or bug it verifies shows up — the plans and sets that contain it, and its repository folder.

Step data this version does not interpret, such as a call to another test, is kept under the step’s “extra” in the record, named in the step table, and noted on stderr.

—json returns the export record (the same shape “test export” writes), not a raw payload, because a test assembled from several sources has none. —raw returns the underlying Jira issue.

Examples

simply atlassian jira xray test get OM-12

simply atlassian jira xray test get OM-12 --fields components,labels --json

simply atlassian jira xray test get OM-12 --raw

simply atlassian jira xray test list

List the tests in a project, plan, set, or repository folder.

Flags

• --project <value> — Project key: every Test in the project, or the folder —path names in it.
• --plan <value> — Test Plan key: its tests, including any added through a Test Set.
• --set <value> — Test Set key: its tests.
• --path <value> — Test repository folder inside —project, such as “/O&M/Accounts”; ”/” is the root.
• --recursive — With —path, include tests in subfolders.
• --jql <value> — Extra JQL ANDed onto the scope, in parentheses so it cannot widen it.
• --search <value> — Text in the summary or description, matched as typed: no wildcards or operators.
• --linked-to <value> — Only tests linked to any of these issues, by any link type. Comma-separated or repeated. (repeatable)
• --fields <value> — Extra fields to return, added to the defaults. Comma-separated or repeated. (repeatable)
• --limit <value> — Maximum number of tests to return. (default: 25)

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Pass exactly one scope — —project, —plan, —set, or —project with —path — and optionally narrow it with —jql, —search, or —linked-to, which are ANDed together. A plan includes the tests that arrived through a Test Set. Everything is one JQL query, so filtering happens on the server.

Use “test export” for full records with steps. —json returns the raw search envelope, like “issue search”: { issues, total, pages, complete }.

Examples

simply atlassian jira xray test list --project OM

simply atlassian jira xray test list --plan OM-7 --search password

simply atlassian jira xray test list --project OM --path "/O&M/Accounts" --recursive

simply atlassian jira xray test list --project OM --linked-to OM-40,OM-41 --fields components

simply atlassian jira xray test step add

Add a step to the end of a manual Xray test.

Flags

• --dry-run — Print the request that would be sent and exit without sending it.
• --action <value> — What the tester does. (required)
• --data <value> — The data the step uses.
• --result <value> — The expected result.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

A new step always goes last: Xray’s API documents no way to place one elsewhere. Returns the test read back, showing the new step and its id. Use —dry-run to see what would be sent without sending it.

Examples

simply atlassian jira xray test step add OM-12 --action "Open Users" --result "The list is shown"

simply atlassian jira xray test step add OM-12 --action "Pick a user" --data bob --dry-run

simply atlassian jira xray test step delete

Delete one step of an Xray test.

Flags

• --dry-run — Print the request that would be sent and exit without sending it.
• --confirm — Required to proceed with an irreversible change.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Irreversible, and it takes the step’s attachments with it, so —confirm is required. “jira xray test get” shows step ids. Use —dry-run to see what would be deleted without deleting it.

Examples

simply atlassian jira xray test step delete OM-12 311 --confirm

simply atlassian jira xray test step delete OM-12 311 --dry-run

simply atlassian jira xray test step update

Edit one step’s action, data, or expected result.

Flags

• --dry-run — Print the request that would be sent and exit without sending it.
• --action <value> — What the tester does.
• --data <value> — The data the step uses. Pass an empty value to clear it.
• --result <value> — The expected result. Pass an empty value to clear it.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Sends only the columns that change. Custom step columns and attachments are left as they are. A step that calls another test is refused. “jira xray test get” shows step ids. Use —dry-run to see what would be sent without sending it.

Examples

simply atlassian jira xray test step update OM-12 311 --result "The list is shown, sorted by name"

simply atlassian jira xray test step update OM-12 311 --data "" --dry-run

simply atlassian jira xray test update

Apply a record or flags to an Xray test, replacing its steps if given.

Flags

• --dry-run — Print the request that would be sent and exit without sending it.
• --confirm — Required to proceed with an irreversible change.
• --file <value> — Path to one test record, as “test get —json” prints it, or one line of “test export —format jsonl”.
• --summary <value> — The summary.
• --type <value> — manual, cucumber, generic, or another type the field allows.
• --step <value> — A step, as ‘action|data|result’. Repeatable; a literal pipe is written |.
• --gherkin <value> — The Cucumber scenario.
• --gherkin-file <value> — Path to a file holding the Cucumber scenario.
• --definition <value> — The generic test definition.
• --field <value> — Another field, as role=value. Repeatable.
• --body <value> — Raw JSON request body, merged underneath.
• --body-file <value> — Path to a file holding the raw JSON request body.

Connection

• -e, --env-file <value> — Path to a .env file holding connection settings.
• --jira-url <value> — Base URL of the Jira instance. (env: JIRA_URL)
• --jira-username <value> — Account email for Jira Cloud basic auth. (env: JIRA_USERNAME)
• --jira-api-token <value> — API token for Jira Cloud basic auth. (env: JIRA_API_TOKEN)
• --jira-personal-token <value> — Personal access token for Jira Server/Data Center. (env: JIRA_PERSONAL_TOKEN)

Only what differs is sent, so an unchanged “test get —json” record writes nothing. Steps given in a record or with —step replace the test’s list: matched by id when the input has ids, by position when it has none. A step missing from the input is deleted, which needs —confirm.

Xray’s API documents no way to reorder steps or to add one at a position, so a reordered list is refused; new steps go after the existing ones. Custom step columns and attachments are left as they are. Use —dry-run to see the plan.

Examples

simply atlassian jira xray test update OM-12 --file ./test.json --dry-run

simply atlassian jira xray test update OM-12 --file ./test.json --confirm

simply atlassian jira xray test update OM-12 --summary "Reset a locked password"