{"id":16671426,"url":"https://github.com/ikluft/moveboxtracker","last_synced_at":"2026-03-11T19:33:40.211Z","repository":{"id":77142638,"uuid":"594650098","full_name":"ikluft/moveboxtracker","owner":"ikluft","description":"moving box tracking: inventory database, label generator","archived":false,"fork":false,"pushed_at":"2024-07-29T05:37:30.000Z","size":1036,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-22T16:41:35.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikluft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-29T07:45:44.000Z","updated_at":"2024-12-10T09:26:58.000Z","dependencies_parsed_at":"2024-07-29T07:17:28.116Z","dependency_job_id":null,"html_url":"https://github.com/ikluft/moveboxtracker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ikluft/moveboxtracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikluft%2Fmoveboxtracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikluft%2Fmoveboxtracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikluft%2Fmoveboxtracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikluft%2Fmoveboxtracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikluft","download_url":"https://codeload.github.com/ikluft/moveboxtracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikluft%2Fmoveboxtracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30395658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T11:44:26.895Z","updated_at":"2026-03-11T19:33:40.164Z","avatar_url":"https://github.com/ikluft.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \"moveboxtracker\" Project Description\n\nThe \"moveboxtracker\" project automates parts of moving box tracking including an inventory database\nand label generation.\n\nThis is the command-line interface (CLI) for moveboxtracker.\nIt manages an SQLite database file containing moving) box data.\nIt prints labels, four to a page, including features I wanted for\ntracking a move based on my experience and advice I found online.\n\nA separate mobile app was intended to handle scanning the QR codes printed on the labels.\nBut it was not ready in time for my move. There is now no guarantee if or when that would be done.\n\n## Project overview\n\nFeatures of the moving box labels:\n\n* box number for database lookup\n* room name and color to help unloading at the destination\n  * color coding rooms is advice I found online, making it easier for helpers\n* QR code for scanning for batches of boxes in each carload or truckload\n* \"lost \u0026 found\" contact info, just in case\n* set \"MBT_PAGE_SIZE\" environment variable to change page size (default: Letter)\n\nTables in the SQLite database:\n\n* batch_move: each batch of boxes moved, time and destination\n* box_scan: code scan event for a box being entered into a move batch\n* image: storage of optional images for moving_box and item records\n* item: description of one of multiple items in a box, optional image\n* location: name of a location, such as origin, storage, destination, etc\n* move_project: overall project info including title, primary user and lost\u0026found contact\n* moving_box: box info including origin/destination room, current location, optional image\n* room: name of origin/destination room\n* uri_user: name of a user as a namespace for URIs for scanning, who did each scan\n\nMore about the database tables are in the [db](db) directory.\n\nLabels are printed with data from a query of the tables move_project, moving_box, room \u0026 uri_user.\nThere are two label formats: 4-up on a page, or a baggage tag.\n\nThe program also prints full-page \"destination sign\" which direct helpers unloading a moving truck where boxes\nlabelled for specific rooms should be placed.\n\nAn Android app was envisioned with the following features. Though it wasn't ready in time to help with my move.\nThere is now no guarantee if or when that would be done.\n\n* Android app\n* QR code scanner using Quickie library https://github.com/G00fY2/quickie\n* scans a batch of boxes into local SQLite db\n* exports SQLite db for merge into central CLI-managed db\n* maybe future expansion to control central db on Android if others want to help with that\n\nThere are no plans for an iOS app unless others want to help develop and maintain it.\n\n## Example labels and signs\n\nThe default for labels is a four to a page.\n\n![example moving label printout page](doc/label-pdf-example.png \"example page-style moving label printout\")\n\nWhen selecting \"bagtag\" labels, two are printed, each about the size of a business card, which can be folded over to be two sides of one laminated baggage tag label.\n\n![example moving label bagtag format](doc/bagtag-labels.png \"example baggage tag style moving label\")\n\nDestination signs print a full page indicating where to unload boxes marked and color-coded for a specific room. These should be placed on the door and/or wall to direct helpers where the boxes with those labels should be unloaded.\n\n![example destination sign page](doc/destsign-pdf-example.png \"example destination sign page\")\n\n## Command-line usage\n\nThe moveboxtracker CLI uses subcommands for different functions and database elements.\nThese are issued like \"moveboxtracker \u003csubcommand\u003e \u003csubcommand-args\u003e\"\nAt any level the --help parameter can show a list of subcommands and options.\n\nThe top-level subcommands are\n\n- init:     initialize new moving box database\n- batch:    create or update a batch record\n- box:      create or update a moving box record\n- destsign: print destination signs, where to unload boxes at destination\n- image:    create or update an image record\n- item:     create or update an item record\n- label:    print label(s) for specified box ids\n- location: create or update a location record\n- room:     create or update a room record\n- scan:     create or update a scan record\n- user:     create or update a user record\n\nThe low-level database subcommands are:\n\n- merge:    merge in an external SQLite database file, from another device\n- dump:     dump database contents to standard output\n- db:       low-level database access subcommands\n\nIn all the commands below, the database file name can be specified by either --db=filename\non the command line or by setting the MBT_DB_FILE environment variable before running the program.\nUse of the environment variable allows setting it once instead of separately on every command.\n\nExample:\n\n    $ export MBT_DB_FILE=/path/to/movebox.db\n    $ moveboxtracker db box read 1\n    executing SQL [SELECT * FROM moving_box WHERE id == :id] with {'id': 1}\n    ┌────┬──────────┬───────────┬──────┬──────┬───────┐\n    │ id │ location │   info    │ room │ user │ image │\n    ├────┼──────────┼───────────┼──────┼──────┼───────┤\n    │ 1  │    1     │ MBR shoes │  2   │  1   │   1   │\n    └────┴──────────┴───────────┴──────┴──────┴───────┘\n    read 1 record(s)\n\n## Top-level subcommands\n\n### init subcommand\n\nBefore a database can be used, the SQLite database file needs to be initialized.\nAny missing data fields will be filled via command-line prompt.\nThe usage is as follows:\n\n    moveboxtracker init [-h] [--primary_user PRIMARY_USER] [--title TITLE] [--found_contact FOUND_CONTACT] DB\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n\ndata field options:\n\n- --id ID:              record id number\n- --primary_user PRIMARY_USER: primary user id to attach to scans\n- --title TITLE:        project name\n- --found_contact FOUND_CONTACT: lost+found contact information to display on labels\n- DB:                   database file path to create and initilize\n\nWhen created the database contains table definitions but no records in any of the tables.\n\n### batch subcommand\n\nThe \"batch\" subcommand creates or modifies a batch record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker batch [-h] [--db DB] [--id ID] [--timestamp TIMESTAMP] [--location LOCATION] [--commit] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --timestamp TIMESTAMP: batch timestamp\n- --location LOCATION:  batch location - where the boxes in this batch are moving to\n\naction options: (actions to take instead of creating or updating a record)\n\n- --commit:             update locations of boxes in this batch to the new location\n- --list:               display a list of the batch records\n\nIt will prompt for required parameters which were not provided on the command line.\nLocation may be either a record id referring to the location table or the name of a location in that table,\nin which case its record id will be retrieved.\n\nSee also the \"db batch\" subcommand for lower level but broader access to the database.\n\n### box subcommand\n\nThe \"box\" subcommand creates or modifies a moving box record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker box [-h] [--db DB] [--id ID] [--location LOCATION] [--info INFO] [--room ROOM] [--user USER] [--image IMAGE] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --location LOCATION:  box location, changes when a batch this box belongs to gets moved\n- --info INFO:          description of the box or unit\n- --room ROOM:          id referring to room table, for printing on box label\n- --user USER:          id referring to user table, originating user for printing on box label\n- --image IMAGE:        id referring to image table (optional)\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the box records\n\nSee also the \"db box\" subcommand for lower level but broader access to the database.\n\n### destsign subcommand\n\nThe \"destsign\" subcommand generates and/or prints destination signs to show which rooms to unload boxes\nat the destination of the move. It directs helpers in the unloading process to bring each box to the correct\nroom based on the room on its label.\n\n    moveboxtracker destsign [-h] [--db DB] [--print] [--outdir LABELDIR] [--all] [ROOM ...]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndestination sign generation options:\n\n- --outdir LABELDIR:      directory to place new label PDF files\n- --all:                  generate destination signs for all rooms - ROOM parameters are not needed when this is used\n- ROOM:                   room name (like \"Kitchen\"), id number (like 23) or range of numbers (like 23-28, no spaces around the dash)\n\nBy default moveboxtracker generates PDF output for US Letter size pages. To use a different page size, set the MBT_PAGE_SIZE environment variable before running the script. For example, to use A3 size pages, set \"export MBT_PAGE_SIZE=A3\" in your shell or its rc setup script before running moveboxtracker.\n\n### image subcommand\n\nThe \"image\" subcommand creates or modifies an image record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker image [-h] [--db DB] [--id ID] [--image_file IMAGE_FILE] [--description DESCRIPTION] [--timestamp TIMESTAMP] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --image_file IMAGE_FILE: relative or absolute path to the image file\n- --description DESCRIPTION: description of the image\n- --timestamp TIMESTAMP: time of the image, defaults to the current time at record creation\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the image records\n\nSee also the \"db image\" subcommand for lower level but broader access to the database.\n\n### item subcommand\n\nThe \"item\" subcommand creates or modifies an item record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker item [-h] [--db DB] [--id ID] [--box BOX] [--description DESCRIPTION] [--image IMAGE] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:                   record id number\n- --box BOX:                 id number of the box which contains the item\n- --description DESCRIPTION: description of the image\n- --image IMAGE:             optional image of the item, as a path to a file or index into the image table\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the item records\n\nSee also the \"db item\" subcommand for lower level but broader access to the database.\n\n### label subcommand\n\nPrinting a label from the database requires providing the database file, a box ID number and a PDF output file. From the database it will also retrieve the lost/found contact info, room name and room color code. Labels are printed duplicated 4 times on a page to have enough to place on 4 sides of a moving box. If more than one box ID number is provided, one page will be made for each set of labels. The resulting PDF file can be sent to any standard printer.\n\n    moveboxtracker label [-h] [--db DB] [--type [TYPE]] [--outdir LABELDIR] ID [ID ...]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\nlabel generation options:\n\n- --type TYPE:            type of label to generate:\n  - \"page\" for a full page with 4 labels (default)\n  - \"bagtag\" for a baggage tag sized label (2 sides to be folded over) which can be laminated into a baggage tag\n- --outdir LABELDIR:      directory to place new label PDF files\n- ID:                     box record id number (like 23) or range of numbers (like 23-28, no spaces around the dash)\n\nBy default moveboxtracker generates PDF output for US Letter size pages. To use a different page size, set the MBT_PAGE_SIZE environment variable before running the script. For example, to use A3 size pages, set \"export MBT_PAGE_SIZE=A3\" in your shell or its rc setup script before running moveboxtracker.\n\n### location subcommand\n\nThe \"location\" subcommand creates or modifies a location record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker location [-h] [--db DB] [--id ID] [--name NAME] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --name NAME:          room name string\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the location records\n\nSee also the \"db location\" subcommand for lower level but broader access to the database.\n\n### room subcommand\n\nThe \"room\" subcommand creates or modifies a room record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker room [-h] [--db DB] [--id ID] [--name NAME] [--color COLOR] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --name NAME:          room name string\n- --color COLOR:        color name string, which must be a valid web color\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the room records\n\nSee also the \"db room\" subcommand for lower level but broader access to the database.\n\n### scan subcommand\n\nThe \"scan\" subcommand creates or modifies a scan record, for recording a movement of a box.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker scan [-h] [--db DB] [--id ID] [--box BOX] [--batch BATCH] [--user USER] [--timestamp TIMESTAMP] [--list | --boxes BOXID [BOXID ...]]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --box BOX:            id number of the box which is being moved\n- --batch BATCH:        id number of the batch group which the box will move along with\n- --user USER:          id referring to user table, originating user who scanned the box or entered its scan data, defaults to the database's default user\n- --timestamp TIMESTAMP: time of the scan, defaults to the current time at record creation\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the room records\n- --commit:             commit the batch move by updating the location of all boxes in the batch to the batch location (requires or will prompt for --id)\n\nSee also the \"db scan\" subcommand for lower level but broader access to the database.\n\n### user subcommand\n\nThe \"user\" subcommand creates or modifies a user record.\nIf an --id parameter is present, it modifies that record.\nOtherwise it creates a new one.\nWhen creating a new record, missing data fields will be filled via command-line prompt.\n\n    moveboxtracker user [-h] [--db DB] [--id ID] [--name NAME] [--list]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\ndata field options:\n\n- --id ID:              record id number\n- --name NAME:          user name string, email address recommended\n\naction options: (actions to take instead of creating or updating a record)\n\n- --list:               display a list of the room records\n\nSee also the \"db user\" subcommand for lower level but broader access to the database.\n\n## Low-level database subcommands\n\n### merge subcommand (not implemented)\n\nThe merge subcommand is not yet implemented. It will collect data from another SQLite database made by the moveboxtracker program or app into the one used by this instance. In particular this is intended as intake for data from the moveboxtracker Android app.\n\n### dump subcommand\n\nThe dump subcommand prints out the contents of the SQLite database file. The path to the database file is a required parameter.\n\n    moveboxtracker dump [-h] [--db DB]\n\ntop-level options:\n\n- -h, --help:           show help message and exit\n- --db DB, --db_file:   DB database file (optional if MBT_DB_FILE is set in the environment)\n\n### db subcommand\n\nThe db subcommand provides direct access to the database tables with create, read, update or delete (“CRUD”)\noperations.\n\n    moveboxtracker db [-h] {batch,box,image,item,location,project,room,scan,user} {create,read,update,delete} ...\n\nThe database tables are:\n\n* batch: batch/group of moving boxes\n* box: moving box including label info\n* image: images for boxes or items\n* item: item inside a box\n* location: location where boxes may be\n* project: overall move project info\n* room: room at origin \u0026 destination\n* scan: box scan event on move to new location\n* user: user who owns database or performs a box scan\n\nEach of the tables supports command-line options named for fields in order to set values.\nFields are required if the database defines them with a \"NOT NULL\" constraint.\n\n#### batch table\n\nEach record in the batch table is a group of boxes moved together.\nThey should be added to the batch as they are loaded into the vehicle.\n\n    moveboxtracker db batch [-h] [--db DB] [--timestamp TIMESTAMP] [--location LOCATION] {create,read,update,delete} [id]\n\n#### box table\n\nEach record in the box table is either a moving box or some other labeled item.\nFor the database's purposes, everything that gets tracked and has a label is simplified to be called a box.\nAny labelled thing, whether or not it is actually a box, will be tracked in the database as a box.\nFor example, a framed picture or a chair also get a label with a \"box\" number.\n\n    moveboxtracker db box [-h] [--db DB] [--location LOCATION] [--info INFO] [--room ROOM] [--user USER] [--image IMAGE] {create,read,update,delete} [id]\n\nThings that go inside a box are in the item table.\n\n#### image table\n\nEach record in the image table describes a photo, stored in a directory named from the basename of the database\nwith a \"-images\" suffix.\nIt also has a hash to recognize if the same image is already in the database.\nA field for the MIME type tells what kind of image it is, and allows looking up what program can display it.\nImages in this table can be referenced by ID from the box or item tables.\n\n    moveboxtracker db image [-h] [--db DB] [--image_file IMAGE_FILE] [--hash HASH] [--mimetype MIMETYPE] [--encoding ENCODING] [--description DESCRIPTION] [--timestamp TIMESTAMP] {create,read,update,delete} [id]\n\n#### item table\n\nEach record in the item table is something that goes inside a box. Each item has a required reference to the box\nthat contains it, required description text and an optional reference to an image of the item.\n\n    moveboxtracker db item [-h] [--db DB] [--box BOX] [--description DESCRIPTION] [--image IMAGE] {create,read,update,delete} [id]\n\n#### location table\n\nEach record in the location table is a place where boxes can be at any stage of a move operation.\nLikely examples would be the origin, one or more storage or staging areas, and the destination.\nThe only field (other than the record ID number) is a text name.\nThe name needs only to be meaningful to the people working on the move.\n\n    moveboxtracker db location [-h] [--db DB] [--name NAME] {create,read,update,delete} [id]\n\n#### project table\n\nThe project contains only one record which is the core configuration of the project.\nIt contains a title string, a reference to the primary user in the uri_user table,\nand a found-contact string to print on moving box labels.\nThere is no \"id\" field because there is only one record.\n\n    moveboxtracker db project [-h] [--db DB] [--primary_user PRIMARY_USER] [--title TITLE] [--found_contact FOUND_CONTACT] {create,read,update,delete} [id]\n\n#### room table\n\nEach record in the room table represents a location at the origin and corresponding location at the destination.\nIt's usually a room but doesn't necessarily have to be.\nAfter the integer primary key field, there are also name and color fields.\nThe name field is a string which will should be short because it will be printed on each box label in large font.\nThe color is a color code for the box labels to make them easier to recognize where to unload them to.\n\n    moveboxtracker db room [-h] [--db DB] [--name NAME] [--color COLOR] {create,read,update,delete} [id]\n\n#### user table\n\nEach record in the user table represents a user who can enter data or scan boxes.\nThis is intended for when merging a database from a mobile device which did scanning.\nAny batches of baxes moved by that device's user will be marked as scanned by them.\nThe name needs to be a unique string.\nIt is recommended to use the email address of the primary user of the mobile device,\nor another string which uniquely represents that person and that device.\n\n    moveboxtracker db user [-h] [--db DB] [--name NAME] {create,read,update,delete} [id]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikluft%2Fmoveboxtracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikluft%2Fmoveboxtracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikluft%2Fmoveboxtracker/lists"}