A lightweight, curl-installable, agentic-first terminal ticket tracker. Manage tasks in plain JSON files — no account, no cloud, no setup friction.

Scope Boundary

Atoshell owns the ticket queue: ticket fields, accountability, dependencies, comments, status transitions, blocker visibility, and JSON import/export. It does not own product specs, delivery definitions, runtime capability checks, implementation orchestration, PR/release state, or project-level handoff metadata.

Use ticket descriptions and comments for concise pointers to external plans, specs, designs, or run artifacts when that helps the person or agent taking the ticket. Atoshell stores those references as ordinary ticket text; it does not validate, interpret, or synchronize external artifacts.

Quick Start

# One-time install on Linux / Git Bash.
curl -fsSL https://raw.githubusercontent.com/GeekKingCloud/atoshell/main/install.sh | bash

cd /path/to/project
atoshell init                                             # set up .atoshell/ in the current directory
atoshell add "Fix the thing" --body "Describe the work."  # create a ticket
atoshell show board                                       # ASCII kanban view (3 active columns by default)
atoshell list                                             # list active tickets
atoshell take next                                        # assign the best ticket (priority/size considered) to me and move to 'In Progress'
atoshell move 1 in progress                               # move ticket #1 (workflow transition)
atoshell move 1 3                                         # same — column 3 = In Progress
atoshell move 1 4                                         # mark done (column 4)
atoshell edit 1 --priority p1                             # also works via edit

Run atoshell with no arguments for an interactive menu:

+--------------------------------------------------+
|            atoshell — Menu                       |
+--------------------------------------------------+

  0) init        — Initialise .atoshell/ in current directory
  1) add         — Create a new ticket
  2) show        — Show a ticket, next ready ticket, or kanban board
  3) edit        — Edit ticket properties
  4) delete      — Delete a ticket
  5) list        — List tickets with optional filters
  6) move        — Move ticket(s) to a new status (by name or column 1-4)
  7) take        — Assign yourself to a ticket and move it to In Progress
  8) comment     — Add, edit, or remove comments
  9) search      — Search ticket content
  10) update     — Update atoshell
  11) uninstall  — Remove atoshell
  12) install    — Install atoshell on this machine
  13) version    — Print the atoshell version

Menu items start at 0 (init) rather than 1 for consistency with common CLI patterns.

Install

# Linux / Git Bash
curl -fsSL https://raw.githubusercontent.com/GeekKingCloud/atoshell/main/install.sh | bash

Requires: bash 4.3 or newer, jq, git.

Atoshell can also be installed from npm-compatible package managers:

bun install -g atoshell
npm install -g atoshell

Package-manager installs still require Bash 4.3 or newer. On Windows, install Git Bash or set ATOSHELL_BASH to a Bash executable. On macOS, install modern Bash with Homebrew and put it before /bin in PATH, or set ATOSHELL_BASH.

After a package-manager install, run the commands directly:

atoshell add "Fix the thing" --body "Describe the work."
ato add "Fix the thing" --body "Describe the work."

For one-off use without a global install:

bunx atoshell version
npx atoshell version
bunx -p atoshell ato version
npx -p atoshell ato version

On macOS, the system /bin/bash is usually too old. Install modern Bash first:

brew install bash jq git
curl -fsSL https://raw.githubusercontent.com/GeekKingCloud/atoshell/main/install.sh | "$(brew --prefix)/bin/bash"

Check the installed CLI version with atoshell version or atoshell -v.

The installer keeps the CLI checkout in ~/atoshell and writes launchers under ~/.local/bin.

On Windows, run the installer from Git Bash. It installs the atoshell and ato shell launchers and also writes atoshell.cmd and ato.cmd so PowerShell and cmd.exe can invoke the same installed CLI names.

CLI Contract

• --quiet|-q suppresses decorative output and is auto-enabled on non-TTY stdout.
• --json|-j is command-local and only belongs after commands that document JSON output, such as atoshell show 5 --json.
• Machine-readable errors for JSON-capable commands are written to stderr as JSON objects; stdout stays clean on failure.
• Run atoshell help, atoshell --help, or atoshell -h for the command menu.
• Run atoshell version, atoshell --version, or atoshell -v for the installed CLI version.
• Run atoshell with no arguments for the interactive menu.

Commands

init

Aliases: kido, boot

Set up .atoshell/ in the current directory. If .atoshell/ already exists, delegates to update instead.

atoshell init

add [title]

Aliases: tasu, fab, new, open

Create a new ticket. If no title is given, opens an interactive prompt.

atoshell add "Fix login bug" --body "Login form fails after submit."
atoshell add "Fix login bug" --priority P1 --size S --description "Details here"
atoshell add "Auth spike" --body "Compare auth options." --disciplines Backend --assign lyra,me
atoshell add "Agent import" --body "Created by orchestrator" --as agent-1
atoshell add --multi                 # keep adding tickets until title is left blank
atoshell add --stream --simple       # rapid-fire: just enter titles, all defaults applied
atoshell add --import tickets.json   # import a batch from a JSON array file
atoshell add --import -              # same, reading from stdin

| Flag / Aliases | Description | Default | |---------------------------------------------|-------------------------------------------------------|------------| | --multi / --stream | Keep adding tickets until title is left blank | | | --simple | Title-only mode — skip all prompts, apply defaults | | | --import <file> | Import from a JSON array (- reads stdin) | | | --description / --desc, --body, -b | Ticket description | (empty) | | --type / --kind, -t | Ticket type (Bug/Feature/Task or 0–2) | Task | | --priority / -p | Priority level (P0–P3 or 0–3) | P2 | | --size / -s | Size estimate (XS/S/M/L/XL or 0–4) | M | | --status / -S | Status to assign (multi-word, no quotes needed) | Ready | | --disciplines / --dis, -d | Fixed discipline tags (comma-separated) | | | --accountable / --assign, -a | Accountable users (me = you, agent = [agent]) | | | --dependencies / --depends, -D | Comma-separated dependency IDs | | | --as <agent-N\|number> | Set created_by to a numbered agent in non-TTY mode | | | --json / -j | Output created ticket as JSON (agent-friendly) | |

--as is only allowed in non-interactive mode and only accepts agent-N or a bare positive number. Omit --as to use the default non-TTY [agent] actor.

--json is non-interactive. It cannot be combined with --multi / --stream or --simple. Single-ticket JSON creation requires both an explicit title and description (--description, --desc, --body, or -b). Bulk import is the title-only easy path: use --import for batch JSON creation where only title is required per item and the remaining fields use project defaults.

Atoshell import is a ticket intake surface, not a project context handoff. Imported descriptions may include links or notes that point to upstream planning material, but Atoshell treats them as ticket text and does not validate referenced files, specs, runtimes, or execution environments.

--discipline and --dependency are also valid aliases. fe and be are accepted as shorthand for Frontend and Backend. When a ticket is deleted, any tickets that depend on it are flagged and you are prompted to remove the dangling reference.

Use the narrowest accurate discipline set when adding tickets. See Disciplines for the fixed labels and when to use each one.

--import format — a JSON array where only title is required:

[
  {"id": 9, "title": "Set up CI", "priority": "P1", "disciplines": ["DevOps"]},
  {"id": 11, "title": "Write tests", "dependencies": [9]}
]

If an imported item includes an id, atoshell treats it as an import-local reference only. New local IDs are assigned on import, and any dependencies that point at other items in the same batch are rewritten to the new IDs automatically. Items without an id keep the existing behavior: dependencies may reference the batch's soon-to-be-assigned local IDs.

Omitted type, priority, size, and status fields use the project's configured defaults (TYPE_2, PRIORITY_2, SIZE_2, and STATUS_READY).

All items are validated before anything is written. Errors across the whole batch are reported together.

show <id|next|board>

Aliases: yomu, read

Show a single ticket in full, the next best ready ticket, or the kanban board.

atoshell show 5
atoshell show 5 --details   # include created/edited timestamps
atoshell show 5 --json      # output ticket as JSON (agent-friendly)
atoshell show next          # best unblocked ready ticket with no assignee or assigned to you
atoshell show next --json
atoshell show board         # ASCII kanban (3 active columns)
atoshell show board --full  # wrap full ticket titles across multiple board lines
atoshell show board --all   # add Done column and show all tickets per column
atoshell show board --done  # same as --all for board

Ticket view (show <id> / show next):

| Flag | Aliases | Description | |--------------|----------|---------------------------------------------------------| | --details | | Show created/edited timestamps for ticket and comments | | --json | -j | Output ticket / next ticket as JSON |

Board view (show board):

| Flag | Aliases | Description | |-----------|----------|------------------------------------------------------------------| | --full | -f | Wrap board cells; continued lines are indented and end with - | | --all | | Add Done column and show all tickets per column | | --done | | Same as --all |

show board is human-readable only. Use list --json or a scoped list <scope> --json command when automation needs structured board or queue state.

Dependency Context (show <id>):

Both human-readable and JSON output include dependency context:

• blocked: true when any dependency is still open
• blocked_by: unresolved dependency objects with id, title, and status
• blocking: open dependent ticket objects with id, title, and status

Example:

$ atoshell show 5
#5: Fix login bug [Bug • P1 • M • Ready]
Created by: Lyra (2 hours ago)
Dependencies: #3
............................................................
Blocked by:   #3 Add auth service [In Progress]
Blocking:     #7

edit <id> [flags]

Aliases: henshu, mod

Edit any property of a ticket. Multiple flags can be combined in a single command.

atoshell edit 7 --title "Revised title"
atoshell edit 7 --description change                                     # opens interactive multi-line prompt
atoshell edit 7 --type Bug --priority P1
atoshell edit 7 --status "in progress"
atoshell edit 7 --status done
atoshell edit 7 --disciplines add Backend --disciplines remove Frontend
atoshell edit 7 --accountable add me,lyra --dependencies add 3,5
atoshell edit 7 --priority P1 --as agent-1
atoshell edit 7 --priority P1 --json

Flags can be combined freely in a single command.

| Flag / Aliases | Values | Description | |---------------------------------------------|------------------------------|-------------------------------------------------------| | --title / -T | <text> or change | Update title; change prompts interactively | | --description / --desc, --body, -b | <text> or change | Update description; change opens multi-line prompt | | --type / --kind, -t | <name> or 0–2 | Set ticket type (0=Bug, 1=Feature, 2=Task) | | --priority / -p | <value> or 0–3 | Set priority (P0–P3) | | --size / -s | <value> or 0–4 | Set size (XS/S/M/L/XL) | | --status / -S | <status> | New status (multi-word, no quotes needed) | | --disciplines / --dis, -d | add\|remove\|clear <vals> | Manage fixed discipline tags (comma-separated) | | --accountable / --assign, -a | add\|remove\|clear <vals> | Manage accountable; me = your name | | --dependencies / --depends, -D | add\|remove\|clear <vals> | Manage dependencies (comma-separated IDs) | | --as <agent-N\|number> | agent-N or N | Set updated_by to a numbered agent in non-TTY mode | | --json / -j | | Output the changed ticket as JSON |

Removing a valid discipline, accountable, or dependency that isn't on the ticket prints a warning but does not fail. Invalid dependency IDs still fail validation. --as is only allowed in non-interactive mode and only accepts agent-N or a bare positive number. --json cannot be combined with interactive change prompts for title or description. fe and be are accepted as shorthand for Frontend and Backend in discipline values. See Disciplines for the fixed labels and when to use each one.

delete <id[,id,...]> [--yes]

Aliases: kesu, wipe

Delete one or more tickets permanently. Prompts for confirmation per ticket unless --yes is passed.

When deleting multiple IDs, missing tickets are reported and skipped — the remaining IDs are still processed. If other tickets list a deleted ticket as a dependency, you will be prompted to remove the dangling reference. --yes removes them automatically.

atoshell delete 5
atoshell delete 3,7,12
atoshell delete 3,7,12 --yes  # skip all confirmation prompts; auto-removes dangling dependencies
atoshell delete 3,7,12 --yes --json

| Flag | Alias | Description | |-----------|--------|---------------------------------------------------------------| | --yes | -y | Skip confirmation prompts; auto-remove dangling dependencies | | --json | -j | Output a deletion summary object; requires --yes |

delete --json returns {deleted, removed_dependencies}. deleted is an array of removed ticket IDs. removed_dependencies contains objects with ticket_id and dependency_id for dependencies removed from surviving tickets.

list [scope] [filters]

Aliases: rekki, draw

List tickets. Defaults to the active queue if no scope is given. Ready tickets are always returned in ranked priority order.

atoshell list                                    # active queue (Ready + In Progress)
atoshell list queue                              # same as default active queue
atoshell list 2                                  # same as: atoshell list ready
atoshell list ready                              # shows all tickets in ready column (status)
atoshell list done                               # shows completed tickets
atoshell list --mine                             # tickets accountable to you
atoshell list --accountable lyra
atoshell list --priority P0,P1
atoshell list --priority 0,1                     # numeric shorthand: P0,P1
atoshell list --type Bug --disciplines Backend
atoshell list backlog --size XS,S --priority P2
atoshell list --status done                      # filter by status — no scope needed, no quotes needed

Scopes:

• Default / active: queue (Ready + In Progress)
• Columns: backlog / bl / 1, ready / rd / 2, in-progress / ip / 3, done / 4
• Other: blockers / deps

Filters: | Flag | Example | |---------------------------------------------|-------------------------------------| | --mine / --me / -M | list --mine | | --accountable <user> / --assign / -a | list --accountable lyra | | --agent / -A | list --agent | | --priority <values> / -p | list --priority P0,P1 or 0,1 | | --size <values> / -s | list --size S,M or 1,2 | | --type <values> / -t | list --type Bug,Feature or 0,1 | | --disciplines <values> / -d | list --disciplines Backend | | --status <value> / -S | list --status in progress |

Filters can be combined freely: atoshell list --mine --disciplines Backend --priority P0

Discipline filters use the fixed labels from Disciplines and accept comma-separated names case-insensitively.

Output flags: | Flag | Aliases | Description | |-----------|----------|----------------------------------------| | --json | -j | Output as JSON array (agent-friendly) |

move <id[,id,...]> <status|column>

Aliases: ido, shift

Move one or more tickets to a new status. Status can be a name (multi-word without quotes) or a column number.

| Column | Status | |---------|--------------| | 1 | Backlog | | 2 | Ready | | 3 | In Progress | | 4 | Done |

atoshell move 8 ready
atoshell move 3,7 in progress      # multi-word, no quotes needed
atoshell move 8 3                  # column number — In Progress
atoshell move 5 4                  # Done
atoshell move 3,7,12 done --quiet
atoshell move 3,7 done --json      # output moved tickets as a JSON array

| Flag | Alias | Description | |------------|--------|---------------------------------------| | --quiet | -q | Suppress output | | --json | -j | Output moved tickets as a JSON array |

Column numbers are shown in the board headers: atoshell show board move --json always returns an array, even when moving one ticket.

take [id|next]

Aliases: toru, snatch, grab

Assign yourself to a ticket and move it to In Progress. With no argument, take defaults to next and takes the best actionable ready ticket automatically.

atoshell take 7
atoshell take
atoshell take next
atoshell take next --json
atoshell take next --disciplines Backend --priority P0,P1
atoshell take 5 --force          # override done guard
atoshell take next --as agent-1  # orchestrator: claim on behalf of a numbered sub-agent
atoshell take next --as 1        # shorthand for agent-1

| Flag / Aliases | Description | |-------------------------------------------|----------------------------------------------------------------------------------| | --as <agent-N\|number> | Assign to a numbered agent (e.g. agent-1 or 1) instead of the default actor | | --type <values> / --kind / -t | Filter next by ticket type (Bug, Feature, Task or 0-2) | | --priority <values> / -p | Filter next by priority (P0-P3 or 0-3, comma-separated) | | --size <values> / -s | Filter next by size (XS-XL or 0-4, comma-separated) | | --disciplines <values> / --dis, -d | Filter next by fixed discipline tags | | --json / -j | Output ticket as JSON after taking | | --force / -F | Override done guard — assign even if Done (id only) |

Notes:

• Filters only apply to take next; use fixed discipline labels from Disciplines.
• next means the best actionable ticket after dependency ordering and cleanup-budget rules, not blindly the highest-priority blocked ticket.
• In a non-TTY context (agent/CI), assigns to [agent] instead of the current user. Use --as <agent-N|number> to assign to a specific numbered agent instead.
• --as is only allowed in non-interactive mode and only accepts agent-N or a bare positive number. Omit --as to use [agent].
• Warns if the ticket is already In Progress — use --force to suppress.
• Errors and does nothing if the ticket is Done — use --force to override, or use atoshell move / atoshell edit to reopen it first. --force cannot be combined with next.
• Exits 1 if the ticket is currently assigned to other users — use --force to override.

comment <id>

Aliases: kaku, mark, note

Add, edit, or remove comments on a ticket. Author is set to $USERNAME when run interactively, or [agent] when stdin is not a TTY (piped input). Use --as <agent-N|number> in non-interactive mode when an orchestrator needs the comment attributed to a specific numbered agent.

atoshell comment 5                                  # interactive prompt
atoshell comment 5 "Looks good"                     # inline text
atoshell comment 5 --as agent-1 "Root cause found"
atoshell comment 5 edit 2 "Updated text"            # edit comment #2
atoshell comment 5 edit 2                           # edit comment #2 interactively
atoshell comment 5 delete 2                         # delete comment #2
atoshell comment 5 "Progress note" --json           # output changed ticket as JSON

--as is only allowed in non-interactive mode and only accepts agent-N or a bare positive number. Omit --as to use [agent]. --json / -j outputs the changed ticket after adding, editing, or deleting a comment. It requires inline comment text for add/edit and cannot be combined with interactive comment prompts.

search <query>

Aliases: hiku, crawl, find

Search across ticket text and common metadata: title, description, comments, disciplines, accountable, type, priority, size, and status.

atoshell search "login"
atoshell search "P0"
atoshell search "login" --json  # output as JSON array (agent-friendly)

| Flag | Alias | Description | |-----------|--------|----------------------------------------| | --json | -j | Output matching tickets as JSON array |

install

Install the CLI locally. install has no subcommand aliases.

atoshell install

| Flag | Aliases | Description | |-------|----------|-------------------| | | | No command flags |

update

Aliases: noru, patch

Pull the latest atoshell CLI and sync project files and config. Git-based installs update with git pull --ff-only; package installs print bun update -g atoshell / npm update -g atoshell guidance; other non-git installs print the manual curl reinstall command instead of executing a remote installer. Creates any missing .atoshell/ files and adds new config vars introduced since the last update.

atoshell update
atoshell update --walk  # search parent directories for a project to update

| Flag | Description | |------------------|--------------------------------------------------------------------------------------| | --walk | Search parent directories for a project to update (default: current directory only) | | --help / -h | Show update usage help and exit |

help

Aliases: --help, -h

Print the command menu and global flag summary.

atoshell help
atoshell --help
atoshell -h

version

Aliases: --version, -v

Print the atoshell CLI version from the checked-in VERSION file.

atoshell version
atoshell --version
atoshell -v

uninstall

Aliases: nuku, purge

Remove atoshell. Your .atoshell/ project data is never touched. Package-manager installs should be removed through the package manager: bun remove -g atoshell or npm uninstall -g atoshell.

atoshell uninstall

Project State

Each project gets a .atoshell/ directory:

.atoshell/
  config.env    # project configuration (gitignored)
  queue.json    # active tickets: Ready → In Progress (committed)
  backlog.json  # parked / untriaged tickets (committed)
  done.json     # completed tickets (committed)
  meta.json     # local metadata such as next_id (gitignored)

queue.json, backlog.json, and done.json are shared project state. config.env and meta.json are local-only.

Ticket schema:

{
  "id": 1,
  "uuid": "2136d109-2e74-42d6-9519-91128337188b",
  "title": "Fix login bug",
  "description": "Full details here",
  "status": "Ready",
  "priority": "P1",
  "size": "S",
  "type": "Bug",
  "disciplines": ["Backend"],
  "accountable": ["lyra"],
  "dependencies": [2],
  "comments": [
    {
      "author": "lyra",
      "text": "Reproduced on staging",
      "created_at": "2026-01-01T01:00:00Z"
    }
  ],
  "created_by": "lyra",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_by": "lyra",
  "updated_at": "2026-01-01T01:00:00Z"
}

created_at and updated_at are written in the timezone configured by ATOSHELL_TIMEZONE in .atoshell/config.env. The default is UTC, which keeps the historical ...Z format. Use IANA timezone names such as ATOSHELL_TIMEZONE="America/Mexico_City" to write local timestamps with an ISO-8601 offset such as 2026-04-23T23:00:00-06:00.

show <id> --json also computes:

• blocked: true when any dependency is still open
• blocked_by: unresolved dependency objects {id,title,status}
• blocking: open dependent ticket objects {id,title,status}

These fields are computed at read time and are not stored on disk.

Config

Each project's .atoshell/config.env controls how atoshell behaves for that project.

Username

Set your name so all tickets and comments are attributed correctly, and so me resolves to you when filtering or setting accountable. If USERNAME is not set in config.env, Atoshell uses undefined.

USERNAME="Vincent"

Status names

Rename to match your workflow.

STATUS_BACKLOG="Backlog"
STATUS_READY="Ready"
STATUS_IN_PROGRESS="In Progress"
STATUS_DONE="Done"

Disciplines

Discipline tags are fixed Atoshell options, not project config. They are used for tagging and filtering work consistently across projects. CLI flags accept comma-separated names case-insensitively; fe and be are shorthand for Frontend and Backend.

| Discipline | Use for | |-----------------|-----------------------------------------------------------------------------------------| | Frontend | UI components, client-side logic, styling, browser APIs, user-facing interactions | | Backend | Server-side logic, REST/GraphQL APIs, services, business rules, data processing | | Database | Schema design, migrations, queries, indexing, data modelling | | Cloud | Cloud infrastructure, managed services (AWS/GCP/Azure), hosting, networking, scaling | | DevOps | CI/CD pipelines, deployment, containerisation, monitoring, operational tooling | | Architecture | System design, technical decisions, service boundaries, cross-cutting concerns, ADRs | | Automation | Scripting, workflow automation, task runners, build tooling (non-test) | | QA | Test writing (unit/integration/e2e), testing strategy, quality gates, bug verification | | Research | Spike work, feasibility studies, technology evaluation, documenting unknowns | | Core | Shared libraries, foundational utilities, cross-service primitives, platform internals |

A ticket may carry multiple disciplines. Use the narrowest set that accurately reflects the work.

Ticket types

Three configurable types — rename to match your workflow.

TYPE_0="Bug"
TYPE_1="Feature"
TYPE_2="Task"

Priority labels

Rename the four priority levels. Order is highest → lowest.

PRIORITY_0="P0"  # highest
PRIORITY_1="P1"
PRIORITY_2="P2"  # default for new tickets
PRIORITY_3="P3"  # lowest

Example — severity labels:

PRIORITY_0="Critical"
PRIORITY_1="High"
PRIORITY_2="Medium"
PRIORITY_3="Low"

Size labels

Rename the five size levels. Order is smallest → largest.

SIZE_0="XS"
SIZE_1="S"
SIZE_2="M"   # default for new tickets
SIZE_3="L"
SIZE_4="XL"

Example — use story points:

SIZE_0="1"
SIZE_1="2"
SIZE_2="3"
SIZE_3="5"
SIZE_4="8"

Dependency budgets

Ready-ticket ranking is built to find quick value without losing sight of important blocked work. Atoshell first orders Ready tickets by dependencies (a Kahn-style topological ranking), then applies priority, size, filters, and the cleanup budget.

When a valuable ticket is blocked, its blocker tickets can be pulled forward ahead of less important work if the blocker cleanup fits the budget for that priority. If the blocked ticket would require too much cleanup, show next / take next skip that chain and return the next best actionable ticket instead.

UNBLOCK_P0_BUDGET=""   # empty = infinite
UNBLOCK_P1_BUDGET="3"

Budget cost comes from size rank: XS=0, S=1, M=2, L=3, XL=4. P0 blockers cost 0, because they are always considered worth clearing. For example, UNBLOCK_P1_BUDGET="3" can pull forward blocker tickets totaling one L, three S, or one S plus one M for a P1 ticket.

Development & Contributing

See STYLE.md for coding standards and contribution guidelines.

Quick start:

• Follow existing code patterns
• Run the smallest relevant tests/unit/<file>.bats first; on Windows use bats.cmd --print-output-on-failure tests/unit/<file>.bats
• Run the full suite only as a final confidence pass
• Submit PRs to the dev branch

License

atoshell is licensed under the GNU General Public License, version 3. See LICENSE.