PageRenderTime 21ms CodeModel.GetById 12ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/README.txt

http://googlecl.googlecode.com/
Plain Text | 305 lines | 239 code | 66 blank | 0 comment | 0 complexity | c3b0a007f40f844a2d725f3bcc95e68c MD5 | raw file
  1 Copyright (C) 2010 Google Inc.
  2
  3 Licensed under the Apache License, Version 2.0 (the "License");
  4 you may not use this file except in compliance with the License.
  5 You may obtain a copy of the License at
  6   
  7      http://www.apache.org/licenses/LICENSE-2.0
  8
  9 Unless required by applicable law or agreed to in writing, software
 10 distributed under the License is distributed on an "AS IS" BASIS,
 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12 See the License for the specific language governing permissions and
 13 limitations under the License.
 14
 15Contents:
 16---------
 171. Introduction
 18  1.1 Other files
 19  1.2 README style
 202. Commands
 21  2.1 Services
 22    2.1.1 Blogger
 23    2.1.2 Calendar
 24    2.1.3 Contacts
 25    2.1.4 Docs
 26    2.1.5 Picasa
 27    2.1.6 Sites
 28    2.1.7 YouTube
 29  2.2 The 'list' task
 303. Options
 31  3.1 Tags
 32  3.2 Date
 33
 341. Introduction
 35Welcome to the README. If you're reading this after checking out the svn repository, this should have the most up-to-date information on the capabilities and usage of the code in svn HEAD. Otherwise, it should more or less match the Manual on the GoogleCL project wiki (http://code.google.com/p/googlecl/wiki/Manual)
 36
 37If you have no idea what this project is or is about, poke around on our home page at http://code.google.com/p/googlecl.
 38
 391.1 Other files
 40For installation instructions, see INSTALL.txt
 41
 42For help with the configuration file, see README.config
 43
 44README.new-usage contains a crash-course in the usage changes from the previous version.
 45
 461.2 README style
 47Wiki markup is used occasionally in this document:
 48  * The '`' character marks example commands.
 49  * '*' denotes an entry in a list (such as this one).
 50
 512. Commands
 52Some terminology:
 53  * service - The Google service being used (Picasa, Blogger, etc.)
 54  * task - The task that the service will be doing (tag, post, delete, etc.)
 55
 56You can also access help by typing `$ google help` or help on a specific service with `$ google help <service>`. For help with available options and what they mean, use `$ google --help`
 57
 582.1 Services
 59Each sub-section corresponds to a service, which lists the available tasks and some options commonly used with that service. Each task follows the format "task: description. `example`". Note that the `example` omits the initial `$ google <service>`
 60
 61You can access a list of available tasks and their options with the "help" command as described above.
 62
 632.1.1 Blogger
 64Common options:
 65  * blog: If you have multiple blogs, you can indicate which one to use. The value you give here the is saved in your config file for future use, if your config file does not already contain an entry for "blog". See ConfigurationOptions.
 66
 67Tasks:
 68  * delete: Delete posts. `delete --title "Silly post number [0-9]*"`
 69  * list: List posts. `list title,url-site`
 70  * post: Upload posts. `post --tags "GoogleCL, awesome" "Here's a really short post. The next posts will be much longer!" ~/blog/2010/may/*`
 71  * tag: Label posts `tag --title "Dev post" --tags "Python, software"`
 72
 73Note: You can use `--owner` to specify another user's blog when listing posts, but you have to provide a Blogger ID (the number in http://www.blogger.com/profile/NUMBER), not the Google account name.
 74
 752.1.2 Calendar
 76Common options:
 77  * cal: Specify the name of the calendar. This can be a regular expression. If this option is not given, the primary calendar is used.
 78  * date: Specify a date, or date range. For the add task, this DISABLES the Quick Add text parsing feature, but allows you to specify when the event occurs. For listing and deleting events, `--date` will only return events that fall on or within the given date(s). Dates are inclusive, so `--date 2010-06-23,2010-06-25` will include the 23rd, 24th, and 25th of June 2010. See the detailed description of the `--date` option below.
 79  * reminder: (for add task only) Add a reminder to the events being added, one per default reminder type in your calendar settings. Default is in minutes, though you can say something like "2h" for one hour, "1d" for one day, etc.
 80
 81Tasks:
 82  * add: Add event to calendar. `add "Dinner party with George tomorrow at 6pm" --reminder 1h`
 83  * delete: Delete an event. `delete --cal "GoogleCL dev cal" --title "Release.*"`
 84  * list: List events. `list --date 2010-06-01,2010-06-30`
 85  * today: List events for today only. `today`
 86
 87*Note:* The add task uses the 'Quick Add' feature unless you specify `--date`. You you can read about Quick Add here: http://www.google.com/support/calendar/bin/answer.py?answer=36604#text
 88*Warning*: Because the add task uses 'Quick Add', it will not work for non-English calendars. See Issue 211. If you have a non-English calendar, use the `--date` option to add events to your calendar.
 89
 902.1.3 Contacts
 91Tasks:
 92  * add: Add contacts. `add "Jim Raynor, jimmy@noreaster.com" contacts.csv`
 93  * delete: Delete contacts. `delete --title Jerkface`
 94  * list: List contacts. `list name,email --title ".*bob.*" > the_bobs.csv`
 95  * add-groups: Add contact groups. `add-groups "Work" "Friends"`
 96  * delete-groups: Delete contact groups. `delete-groups "Friends"`
 97  * list-groups: List contact groups. `list-groups "my group"`
 98
 992.1.4 Docs
100Common options:
101  * format: Force docs to use the extension you provide.
102  * folder: Specify a folder on Docs to search in or upload to.
103
104Tasks:
105  * delete: Delete docs. `delete --title "Evidence"`
106  * edit: Edit or view a document. `edit --title "Shopping list" --editor vim`
107  * get: Download docs. `get --title "Homework [0-9]*"`
108  * list: List documents. `list title,url-direct --delimiter ": "`
109  * upload: Upload documents. `upload the_bobs.csv ~/work/docs_to_share`
110
111Note: Uploading arbitrary files is only possible for Apps Premier customers, using the --no-convert option. See the FAQ.
112
1132.1.5 Picasa
114Common options:
115  * owner: Owner of the albums you want to deal with. This will work with all tasks but create and delete. For example, to download bob's album, add `--owner bob` to the "get" task. To post to your friend's album that she shared with you, add `--owner your_friend` to the "post" task.
116
117Tasks:
118  * create: Create an album. `create --title "Summer Vacation 2009" --tags Vermont ~/photos/vacation2009/*`
119  * delete: Delete photos or albums. `delete --title "Stupid album"`
120  * get: Download photos. `get --title "My Album" /path/to/download/folder`
121  * list: List photos or albums. `list title,url-direct --query "A tag"`
122  * post: Add photos to an album. `post --title "Summer Vacation 2008" ~/old_photos/*.jpg`
123  * tag: Tag photos. `tag --title "Album I forgot to tag" --tags oops`
124
1252.1.6 Sites
126All sites pages have a contentEntryID, a value that uniquely identifies it. Some commands use this value.
127Common options:
128  * domain: If your site has a domain, either specify it in config or with this option
129  * site: This is a particular site out of all the sites that you can access. Also can be in config.
130
131Tasks:
132  * sites: show all the sites that you can see/access (site feed).
133  * list: List site pages for the site (content feed). By default, lists 'first page' of results: option/config parameter max_queries can increase this. `list --site=mysite --max_results=50`. The --query option does a full text search, returning pages that match: `list --site=mysite --query="some text"`. Finally, other queries (path, kind, parent, ancestor) can be specified: `list --site=mysite path=/path/to/page`, `list --site=mysite parent=contentEntryID`, `list --site=mysite kind=webpage`.
134  * upload: Upload a page to sites, optionally as a subpage: `upload --site=mysite --src=file --title=page_name --folder=parent_path --format=webpage`. Default format is webpage, see https://developers.google.com/google-apps/sites/docs/1.0/reference#feed_Content for more. folder is the path to the parent; default is top-level of site.
135  * delete: delete a page from a site: `delete site=mysite --title=/path/to/page`. 
136
1372.1.7 YouTube
138Common options:
139  * category: YouTube category to assign to the video. This is required, and a little tricky. Here's the mapping for YouTube categories to `--category` values (and capitalization counts!)
140|| *YouTube category* || *Value for* `--category` ||
141|| Autos & Vehicles || Autos ||
142|| Comedy || Comedy ||
143|| Education || Education ||
144|| Entertainment || Entertainment ||
145|| Film & Animation || Film ||
146|| Gaming || Games ||
147|| Howto & Style || Howto ||
148|| Music || Music ||
149|| News & Politics || News ||
150|| Nonprofits & Activism || Nonprofit ||
151|| People & Blogs || People ||
152|| Pets & Animals || Animals ||
153|| Science & Technology || Tech ||
154|| Sports || Sports ||
155|| Travel & Events || Travel ||
156
157Tasks:
158  * delete: Delete videos. `delete --title ".*"`
159  * list: List your videos. `list`
160  * post: Post a video. `post --category Education --devtags GoogleCL killer_robots.avi`
161  * tag: Tag videos. `tag -n ".*robot.*" --tags robot`
162
1632.2. The List task
164The list task can be given additional arguments to specify what exactly is being listed. For example,
165
166`$ google <service> list field1,field2,field3 --delimiter ": "`
167
168will output those fields, in that order, with ": " as a delimiter. Valid values for `<`field1`>` etc. are dependent on the service being used.
169
170Common (all services):
171
172*Note:* These are enabled for all services, but the service may not have a definition for it. For example, Docs does not support summaries.
173  * 'summary' - summary text. Includes Picasa captions.
174  * 'title', 'name' - displayed title or name.
175  * 'url' - treated as 'url-direct' or 'url-site' depending on setting in preferences file. See the note at the end of this section.
176  * 'url-site' - url of the site associated with the resource.
177  * 'url-direct' - url directly to the resource.
178  * 'xml' - dump the XML representation of the result.
179
180Blogger:
181  * 'access' - access level of the post (either 'public' or 'draft')
182  * 'author' - author of the post
183  * 'tags', 'labels', - tags or labels on the post.
184
185Calendar:
186  * 'when' - when an event takes place.
187  * 'where' - where the event takes place.
188
189Contacts:
190  * 'address', 'where' - postal addresses.
191  * 'birthday', 'bday' - birthday.
192  * 'email' - email address(es).
193  * 'event', 'dates', 'when' - events such as birthdays, anniversaries, etc.
194  * 'im' - instant messanger handles.
195  * 'name' - full name.
196  * 'nickname' - nickname.
197  * 'notes' - notes on a contact.
198  * 'organization', 'company' - company or organization.
199  * 'phone_number', 'phone' - phone numbers.
200  * 'relation' - names of relations, such as manager, spouse, etc.
201  * 'title', 'org_title' - job title.
202  * 'user_defined', 'other' - custom labels.
203  * 'website', 'links' - websites and links.
204
205Picasa:
206  * Photos (picasa list)
207  ** 'caption', 'summary' - photo caption
208  ** 'distance' - distance between camera and target.
209  ** 'ev' - exposure value.
210  ** 'exposure' - exposure time.
211  ** 'flash' - if flash was used.
212  ** 'focallength'- focal length used.
213  ** 'fstop' - focal length divided by "effective" aperture diameter (aka f-number, focal ratio, or relative aperture)
214  ** 'imageUniqueID', 'id' - EXIF identifier assigned uniquely to each image.
215  ** 'iso' - iso equivalent value used.
216  ** 'make' - make of the camera used.
217  ** 'model' - model of the camera used.
218  ** 'tags' - tags on the photo.
219  ** 'time', 'when' - time the photo was taken (as millisecond timestamp).
220  ** 'url-download' - link directly to download an image.
221  * Albums (picasa list-albums)
222  ** 'access', 'visibility' - visibility setting on the album.
223  ** 'location', 'where' - location text of the album properties.
224  ** 'published', 'when' - when the album was uploaded
225
226YouTube:
227  * 'author', 'owner' - username of video uploader.
228  * 'minutes', 'time', 'length', 'duration' - length of the video, in MM:SS format. (Note that if you specify ':' as a delimiter, it will be MM SS).
229  * 'seconds' - length of the video in seconds.
230  * 'status' - status of the video. This is still an uncertain feature.
231  * 'tags' - tags on the video.
232
233The difference between 'url-site' and 'url-direct' is best exemplified by a picasa photo: 'url-site' gives a link to the photo in the user's album, 'url-direct' gives a link to the image url. If 'url-direct' is specified but is not applicable, 'url-site' is placed in its stead, and vice-versa.
234
2353. Options
236GoogleCL will fill in options in what it hopes is a natural way. If you do not specify any options explicitly with `-<letter>` or `--<option>`, the program will suck in values from the command line to replace the missing required options. For example,
237`$ google help contacts`
238...
239`list: List contacts`
240`   Requires: fields AND title AND delimiter`
241
242says that `--fields --title --delimiter` are all required. If you haven't changed your basic configuration, there should be a line under the config header `[CONTACTS]` that says `fields = name,email`, so that required option is fulfilled. (Note that there is a `fields` entry under `[GENERAL]` so you never need to supply a value for `fields`, and shouldn't, unless you specify it with `--fields=<my new fields>`)
243
244Next up is `title`, so if you issue the contacts list command with any free-floating arguments, the first one will be set to `title`.
245
246Finally, `delimiter` is always set to "," by default, so that's satisfied as well.
247
248This means that
249
250`$ google contacts list Huey Dewey Louie`
251`$ google contacts list Huey Dewey Louie --fields name,email`
252`$ google contacts list --fields name,email --title Huey Dewey Louie`
253
254all give the same output.
255
256Some tasks have a conditional requirement, such as (title OR query). In this case, `title` is filled first, and GoogleCL assumes you do not want to specify a query. Of course, if you filled `query` explicitly and not `title`, `title` is not filled in with any command line arguments.
257
258Here are some more details on the trickier options you can specify.
259
2603.1 Tags
261The tags option will let you both add and remove tags / labels. Here are some examples:
262  * 'tag1, tag2, tag3': Add tag1, tag2, and tag3 to the item's tags
263  * '-tag1, tag4': Remove tag1, add tag4
264  * '-- tag5': Remove all tags, then add tag5
265
2663.2 Date
267The behavior given here is applicable to the calendar service.
268
269  * '[datetime]': Specify date/time.
270  * '[datetime],': On and after given date/time.
271  * '[starting datetime],[ending datetime]': Between the two dates/times, inclusive
272  * ',[datetime]': On or before date/time.
273
274The contents of [datetime] can follow several formats. You can specify a date with any of the following:
275
276  * today/tomorrow
277  * YYYY-M-D ("2010-9-25")
278  * M/D[/YY or /YYYY] (e.g. "9/2", "9/2/10", "9/2/2010")
279  * Month/mo. D [YYYY] (e.g. "January 1", "Feb 20", "Dec 31 1999")
280
281You can specify a time in most typical formats:
282
283  * hour [am or pm] (e.g. "3pm", but NOT just "23")
284  * hour:minute [am or pm] (e.g. "10:30am" "11:45", "23:00")
285
286  but note that if you specify a time without specifying am or pm, it will be converted the same way Google Calendar Quick Add does. 1-6 are interpreted as "pm", 7-12 are "am". So "6" will be interpreted as "18:00".
287
288Finally, you can combine a date and time with "at" or "@"
289
290  * 11/3 @ 5:30pm
291  * Feb 5 at 16:00
292  * tomorrow @ 3:33am
293
294In case those weren't enough options for you, you can specify an offset by prefixing a number with "+", which is interpreted based on where it appears in the date expression. Appearing by itself, it translates to an offset from the current time. After a datetime and comma, it translates to an offset from the previous datetime.
295
296  * '+3': A time of "three hours from now"
297  * '1/1/11 at 4pm,+2': A range of "1/1/11 at 4pm" to "1/1/11 at 6pm"
298  * '+4,+1': A range of "four hours from now" to "five hours from now"
299
300See the example scripts for examples on how to use this option.
301
302*Note:* the calendar delete task will interpret 'datetime,' and ',datetime' identically.
303
304*Note:* picasa create will only accept the "date" portion of possibilities for `--date`
305